OpenIDConnect with PhenixID Authentication Services - overview
This document describes how PhenixID Authentication Services can be used in OpenIDConnect scenarios. For more information about the OpenIDConnect standard, please visit http://openid.net/connect/
Role
PhenixID Authentication Services can be used as an OpenID Connect Provider, ie handling the authorization of users and issuing tokens to the relying parties on behalf of the users.
Supported flows
PhenixID Authentication Services supports:
- Authorization Code flow
- Implicit flow
Technical flow
The picture below illustrates the data flow in OpenIDConnect Authorization Code flow.
The relying party (client) can be a web application, a native mobile app, a rich client application or any system/platform/device/service.
The user agent can be the system web browser or a web browser component built inside the relying party client. PhenixID recommends to use the system web browser. Using the system web browser will make Single-Sign-On (SSO) feasible between apps and systems.
The OpenID Connect Provider (PAS) provides an authorization endpoint URL for user authentication.
For authorization code flow, it also provides a token endpoint URL for token issuing.
Authorization code flow
1. User opens relying party client (such as a mobile app) and clicks login. User agent will redirect to the authorization endpoint with client specific data added to the query string. https://<openid_connect_provider_PAS_authorization_endpoint_url>?client_id=myMobileApp&redirect_uri=myMobileApp://
2. PAS will verify the client_id and redirect_uri against configured relying party trust configuration. PAS will prompt for authentication.
3. User authenticates. Depending on the authentication method, several calls from the user agent to PAS might occur.
4. If authentication is successful, PAS will generate an authorization code. PAS will return URL to user agent (<redirect_uri>?code=<authorization_code>. Example: myMobileApp://?code=123456
5. User agent will launch URL from 4. This will trigger the relying party client. The relying party client will receive the code from the URL.
6. The relying party backend will call the token endpoint. https://<openid_connect_provider_PAS_token_endpoint_url>?code=<code>&redirect_uri=<redirect_uri>&client_id=myMobileApp&client_secret=XXXX
PAS will return a signed OpenIDConnect JWT IDToken. This token contains information about the end user that performed the successful authentication. The relying party will validate the JWT token (signature and other attributes). If validation is ok, the user is granted access to the relying party.
Implicit flow
- User opens application/app and clicks Login.
- Application redirects user agent to the OpenID Connect Provider (PAS) authorization endpoint, asking for authentication. The url for the authorization endpoint follows this pattern:
https://<pas_server>/oidc/authenticate/<alias_for_http_authenticator>?response_type=id_token
&client_id=<client_id>&scope=openid&state=<opaque_state>
&redirect_uri=http%3a%2f%2flocalhost%3a49628%2fauth-callback&nonce=<myNonceValve>
Parameters explained:
- response_type Must be id_token or id_token token for this flow.
- client_id The id of the client (RP). This is given to the RP by the PAS admin based on PAS configuration (see other solution doc)
- state [Optional] State value passed by the RP. Same parameter, unchanged, will be returned to the RP with the token.
- redirect_uri The redirect uri where the token response (or error) will be passed by PAS. Must be an allowed value (based on PAS configuration, see other solution doc)
- nonce [OPTIONAL] Value to strengthen security and avoid man-in-the-middle attacks. The exact same value will be returned as a token claim. By using this, the RP can make sure the token belongs to a authorization request. Recommended to use.
The user authenticates. Authentication method(s) may vary depending on configuration - If authentication was successful, PAS will redirect the user agent to the redirect_uri. The encoded id_token (jwt format) will be added to the response.
<redirect_uri>#id_token=<encoded_signed_jwt_id_token>&state=<state>
If responsetype included token, an access token is appended to the response.
<redirect_uri>#id_token=<encoded_signed_jwt_id_token>&state=<state>&access_token=0123456789abcdefghijABCDEFGHIJ
Example 1 - id_token
Authorization endpoint:
After authentication, the user agent is redirected to redirect_uri with an id_token.
Example 2 - id_token token
Authorization endpoint:
&redirect_uri=http%3a%2f%2flocalhost%3a49628%2fauth-callback&nonce=myNonceValue
After authentication, the user agent is redirected to redirect_uri with an id_token.
http://localhost:49628/auth-callback
&state=MyState&access_token=0123456789abcdefghijABCDEFGHIJ
Useful tools for debugging:
To decode jwt tokens, please use an online tool, like jwt.io. For example, the id_token above will be decoded to:
Header:
{
"alg": "RS256",
"typ": "JWT"
}
Payload:
{
"sub": "anders",
"iat": 1537351276,
"nbf": 1537351276,
"exp": 1537351366,
"jti": "aef6812a-8897-4f01-9376-a6ea51478a06",
"nonce": "myNonceValue",
"aud": "omega",
"iss": "https://demo.phenixid.net",
"amr": "pwd",
"given_name": "Anders",
"family_name": "Eldebrink"
}
The RP must verify the signature using the public certificate that was given out by the PAS administrator.
Configuration
Setup PAS as an OpenIDConnect Provider
How to configure PhenixID Authentication Services as an OpenIDConnect Provider (OP) - Authorization code flow
How to configure PhenixID Authentication Services as an OpenIDConnect Provider (OP) - Implicit flow
Relying party integration guide
OpenIDConnect - integration guide for developers - Authorization Code flow
OpenIDConnect - integration guide for developers - Implicit flow