OpenIDConnect Implicit 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 Implicit 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

- client_id

- 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

id_token

This is the start of the authentication.

  1. Build a url with a query string with this pattern:
    <authorization_endpoint_url>?response_type=id_token
    &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) if you are not running your own embedded user agent.

If the authorization was successful (ie, the user authenticated), the OpenID Connect Provider will redirect to the redirect_uri with an id_token. Fetch the id_token from the URI fragment.

redirect_uri#id_token=<encoded_token>

id_token token

This is the start of the authentication.

  1. Build a url with a query string with this pattern:
  2. <authorization_endpoint_url>?response_type=id_token token
  3. &client_id=<value_given_to_you_by_op_provider_admin>
  4. &scope=openid
  5. &redirect_uri=<url_encoded_redirect_uri>&nonce=<nonce_value_random_string_generated_by_you>
  6. &state=<optional_state_value_which_will_be_returned_in_response>
  7. Launch the url:
  8. - If you are a web application, simply redirect (HTTP GET) to the url
  9. - If you are an app, rich client or any non-web-based system, launch the url in the system web browser (HTTP GET) if you are not running your own embedded user agent.

If the authorization was successful (ie, the user authenticated), the OpenID Connect Provider will redirect to the redirect_uri with an id_token and access_token. Fetch the tokens from the URI fragment.

redirect_uri#id_token=<encoded_token>&access_token=<access_token>

Consuming and verifying the token(s)

id_token

The id_token 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

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.