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
- 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.
- Build a url with a query string with this pattern:
- 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.
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:
This should return an HTTP status code 200 with a JSON string in the response body.
Consuming and verifying the 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]
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 retrieve UserInfo or verify user session on subsequent calls to backend services.
More information about session verification can be found here.
Please view an OpenIDConnect Relying Party example here. Authenticate with any username and password.
Please be aware that this is only a demo sample! In real-world scenarios, the exchange of the authorization code for a token MUST ALWAYS be executed on the backend, ie server-to-server.
To retrieve UserInfo (additional clams (attributes)) follow this guide.