OpenIDConnect Authorization Code Flow - integration guide for developers

This document describes how to integrate your application, app, system or rich client with PhenixID Authentication Services using OpenIDConnect.

The target audience of this document is system developers.

Please read through this document first to get an overview of the OpenIDConnect Authorization Code Grant Flow.

The goal of the integration is to make your application, app, system or rich client an OpenIDConnect Relying Party to be able to integrate with PhenixID Authentication Services.

What you need to get started

In order to get started, the administrator of the OpenIDConnect Provider (PhenixID Authentication Services) must provide you with these details:

- Authorization endpoint URL

- Token endpoint URL

- client_id

- client_secret

- Token signing public certificate (in PEM format)

What you need to provide

For security reasons, you must provide this information to the administrator of the OpenIDConnect Provider (PhenixID Authentication Services):

- redirect_uri. A list of URIs (usually only one) that you will use for the redirect_uri parameter which will tell the OpenIDConnect Provider where to redirect the user agent after successful authorization.
Please be aware that this must not be a http/https URL! For non-web-based systems this is most likely something like myschema://auth/callback/

Sending the client to the authorization endpoint

This is the start of the authentication.

  1. Build a url with a query string with this pattern:
    <authorization_endpoint_url>?response_type=code
    &client_id=<value_given_to_you_by_op_provider_admin>
    &scope=openid
    &redirect_uri=<url_encoded_redirect_uri>
    &nonce=<nonce_value_random_string_generated_by_you>
    &state=<optional_state_value_which_will_be_returned_in_response>
  2. Launch the url:
    - If you are a web application, simply redirect (HTTP GET) to the url
    - If you are an app, rich client or any non-web-based system, launch the url in the system web browser (HTTP GET)

Consuming the authorization code

If the authorization was successful (ie, the user authenticated), the OpenID Connect Provider will redirect to the redirect_uri with an authorization code in the query string. Fetch it from the code parameter of the query string.

redirect_uri?code=<authorization_code>

Calling the token endpoint to exchange the authorization code for a token

This procedure must happen on the backend! It must never be executed on the client.

Perform an HTTP POST to the token endpoint URL with this data:

code=<code_from_previous_step>
&client_id=<value_given_to_you_by_op_provider_admin>
&scope=openid
&redirect_uri=<url_encoded_redirect_uri>
&client_secret=<value_given_to_you_by_op_provider_admin>
&grant_type=authorization_code

This should return an HTTP status code 200 with a JSON string in the response body.

Consuming and verifying the token

ID token

From the json response, fetch the id_token parameter value. This is the actual OpenID Connect ID Token containing information about the authorized subject (user). The ID token is a JWT token.

1. Decode the JWT Token.
2. Verify the JWT Token according to https://openid.net/specs/openid-connect-core-1_0.html#IDTokenValidation

Use the token signing public certificate to verify the signature of the token.

3. If verification was successful, fetch the sub parameter from the ID token. This contains the userID. The user now should gain access to the system.

 

Access token [OPTIONAL]

[OPTIONAL]

If you need an access_token for calls to subsequent services, make sure the OIDC Provider administrator configured PhenixID Authentication Services to return such a token.

The access_token is bound to a PhenixID Authentication Services authenticated user session. The access_token can be used to verify user session on subsequent calls to backend services. Details about that flow is not specified in this content.

Example

Please view an OpenIDConnect Relying Party example here. Authenticate with any username and password.

This example is written in javascript only in order for you to view the flow in code.
Please be aware that this is only a demo sample using a static client_secret stored in the browser.