Getting access tokens using the authorization code grant with mTLS

Instructions for getting access tokens using the authorization code grant with mTLS.

Prerequisite

The client has files key.pem and cert.pem containing private and public keys.

Login as admin in Swagger UI

  1. Go to https://localhost:8443/api/swagger/default.

  2. Select Authorize.

  3. Enter the following values in the form:

    Key Value
    client_id admin-swagger
    client_secret n8HF35qzZkmsukHJzzz9LnN8m9Mf97uq
  4. Select Authorize.

  5. Select Close.

Client configuration

The OAuth client authenticates to the authorization server using the mutual TLS based on the public key infrastructure (PKI).

The client needs to set one of the following attributes based on its certificate:

  • tls_client_auth_subject_dn
  • tls_client_auth_san_dns
  • tls_client_auth_san_uri
  • tls_client_auth_san_ip
  • tls_client_auth_san_email

Note

If you want the authorization server to embed the certificate hash into access tokens, set "tls_client_certificate_bound_access_tokens": true (it’s disabled by default).

Create the client

  1. Select the POST /api/admin/{tid}/clients API.

  2. Select Try it out.

  3. Enter default as tid (tenant ID).

  4. Use the following json as the body:

    {
        "authorization_server_id": "default",
        "client_id": "client-mtls",
        "client_name": "My app",
        "grant_types": [
          "authorization_code"
        ],
        "redirect_uris": [
            "https://example.com/callback"
        ],
        "token_endpoint_auth_method": "tls_client_auth",
        "tls_client_auth_subject_dn": "example.com",
        "tls_client_certificate_bound_access_tokens": true,
        "response_types": [
          "token",
          "id_token",
          "code"
        ],
        "scopes": [
          "email",
          "openid"
        ]
    }
    
  5. Select Execute.

Make the authorize request

  • Your application initializes a redirect in the browser to the following url:

    https://localhost:8443/default/default/oauth2/authorize
    ?client_id=client-mtls
    &scope=openid
    &redirect_uri=https%3A%2F%2Fexample.com%2Fcallback
    &response_type=code
    
  • The user authenticates and approves the access to the data on the consent page.

    Note

    To test the authentication, you can use the user:user credentials.

Exchange the authorization code

  • Once the user has granted the access to the application, the authorization server makes a redirect to the requested redirect_uri with the authorization code in the query parameter.

    https://example.com/callback
    ?code=2Y5tKqa2bLn6Mz7I7h2NuUgoUOFzUquBnuwDeg2431k
    
  • Your application exchanges the authorization code for the access and ID tokens.

    curl -X POST -k https://localhost:8443/default/default/oauth2/token \
    --key key.pem --cert cert.pem \
    -H "Content-type: application/x-www-form-urlencoded" \
    -d "grant_type=authorization_code&client_id=client-mtls&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback&code=2Y5tKqa2bLn6Mz7I7h2NuUgoUOFzUquBnuwDeg2431k"
    

Expected response

{
   "access_token": "..",
   "expires_in": 3600,
   "id_token": "..",
   "scope": "openid",
   "token_type": "bearer"
}

Note

If the certificate bound access token has been enabled for the client, the access token needs to contain the client certificate hash under the cnf claim, for example

{
  "cnf":{
    "x5t#S256": "bwcK0esc3ACC3DB2Y5_lESsXE8o9ltc05O89jdN-dg2"
  }
}