PhenixID DocumentationPhenixID Authentication ServicesSolutionsOpenIDConnect (OIDC) / OAuthOpenIDConnect with PhenixID Authentication Services - overview

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

  1. User opens application/app and clicks Login.
  2. 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
  3. 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:

https://demo.phenixid.net/oidc/authenticate/oidc_impl?response_type=id_token&client_id=omega&scope=openid&state=MyState
&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
#id_token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhbmRlcnMiLCJpYXQiOjE1MzczNTEyNzYsIm5iZiI6MTUzNzM1MTI3NiwiZXhwIjoxNTM3MzUxMzY2LCJqdGkiOiJhZWY2ODEyYS04ODk3LTRmMDEtOTM3Ni1hNmVhNTE0NzhhMDYiLCJub25jZSI6Im15Tm9uY2VWYWx1ZSIsImF1ZCI6Im9tZWdhIiwiaXNzIjoiaHR0cHM6Ly9kZW1vLnBoZW5peGlkLm5ldCIsImFtciI6InB3ZCIsImdpdmVuX25hbWUiOiJBbmRlcnMiLCJmYW1pbHlfbmFtZSI6IkVsZGVicmluayJ9.ZJGKPHqrXRj5NCpomv6GqreKpmTHuxa_X6dnM3UcVlFR2D57nLQD7PdXLMMysVO4tOa6ZGPlBkTdr6sN2MF5chvPpyKRyvPF4v-9nBf1EVlwdyIQE3ovefhItK9YELtpDEeGu4C8eGoUpDmyh0cKuhf3Os372Q-XNJzWUDPZzuZfFJYQi-8m4RZIunBuLn63DaPAW89jqrzE9CElW2GMldo_fmE-DJnrqm12X8nwfpOShgLinRawsd4TXw6zrkWIc31IjLmZPJKcZRyhvlhL0wvW38DUnyyo2ZBFRIw_ed0MicIySoWlTih_NvHPphPfkbSFGjSByH3UxeL6xz_H9g
&state=MyState

 

Example 2 - id_token token

Authorization endpoint:

https://demo.phenixid.net/oidc/authenticate/oidc_impl?response_type=id_token token&client_id=omega&scope=openid&state=MyState

&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

#id_token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhbmRlcnMiLCJpYXQiOjE1MzczNTEyNzYsIm5iZiI6MTUzNzM1MTI3NiwiZXhwIjoxNTM3MzUxMzY2LCJqdGkiOiJhZWY2ODEyYS04ODk3LTRmMDEtOTM3Ni1hNmVhNTE0NzhhMDYiLCJub25jZSI6Im15Tm9uY2VWYWx1ZSIsImF1ZCI6Im9tZWdhIiwiaXNzIjoiaHR0cHM6Ly9kZW1vLnBoZW5peGlkLm5ldCIsImFtciI6InB3ZCIsImdpdmVuX25hbWUiOiJBbmRlcnMiLCJmYW1pbHlfbmFtZSI6IkVsZGVicmluayJ9.ZJGKPHqrXRj5NCpomv6GqreKpmTHuxa_X6dnM3UcVlFR2D57nLQD7PdXLMMysVO4tOa6ZGPlBkTdr6sN2MF5chvPpyKRyvPF4v-9nBf1EVlwdyIQE3ovefhItK9YELtpDEeGu4C8eGoUpDmyh0cKuhf3Os372Q-XNJzWUDPZzuZfFJYQi-8m4RZIunBuLn63DaPAW89jqrzE9CElW2GMldo_fmE-DJnrqm12X8nwfpOShgLinRawsd4TXw6zrkWIc31IjLmZPJKcZRyhvlhL0wvW38DUnyyo2ZBFRIw_ed0MicIySoWlTih_NvHPphPfkbSFGjSByH3UxeL6xz_H9g

&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.