OpenID Connect
OpenID Connect 1.0 (OIDC) is a simple identity layer on top of the OAuth 2.0 protocol. It allows Clients to verify the identity of the End-User based on the authentication performed by an Authorization Server, as well as to obtain basic profile information about the End-User in an interoperable and REST-like manner.
OpenID Connect allows clients of all types, including Web-based, mobile, and JavaScript clients, to request and receive information about authenticated sessions and end-users. The specification suite is extensible, allowing participants to use optional features such as encryption of identity data, discovery of OpenID Providers, and session management, when it makes sense for them. (Source: OpenID Connect)
As in many SSO solutions, there are two main roles defined by OIDC: The Identity Provider (IP) and the Relaying Party (RP). The IP is similar to a SAML Identity Provider (SAML IDP). The identity provider (IP) implements a set of services that can be consumed to establish the identity of a user. The relaying party (RP) is similar to a SAML Service Provider(SAML SP), and consumes identity services available at the IP.
JOSSO can play both roles, an RP by consuming identity services, provided for instance for social services like Google or Facebook; and an IP, by serving OIDC RPs configured as trusted in JOSSO.
For more details on the protocol please refer to http://openid.net/
Scope
This tutorial focuses on the scenario that requires JOSSO to play the IP role. We will go through the process of modeling and configuring a relying party in JOSSO. The actual implementation of the OIDC support in the application is outside the scope of this tutorial. Depending on the application technology, there are several options that support OIDC out of the box. Keep in mind that OIDC includes other standards like OAuth 2 or Jason Web Tokens. You can find different tools here: http://openid.net/developers/libraries/
Prerequisites
Before we get started, make sure that you have an OpenID connect application. You can use our Java example if you want to. You can find our example at: https://github.com/atricore/atricore-idbus/tree/1.5.2/examples/oidc-client
Configuring Identity Appliance Elements
We are going to add a new element to the identity appliance: an External OpenID Relaying Party available in the Providers drawer. The element connects to the desired identity provider using a federated connection. Let’s take a look at the diagram:
Identity Provider (IP)
Normally we already have an IdP configured in our environment, but we will go through the process of configuring it in this example. From the Providers section we add an Identity Provider to the model. The only change we are making is enabling the OpenID 2.0 protocol option. The other IdP-related settings for OIDC are available at the OIDC RP definition, allowing for specific OIDC IP settings for each RP.
Identity Source
In this case we are using the Identity Vault, a built-in users repository provided by JOSSO. You can use your own specific identity source.
Relaying Party (RP)
When defining a new relaying party, we must provide a set of properties to reflect how the OIDC connection is configured. These properties must be shared between the RP and the IDP. Each RP toolkit has different ways to configure these options.
In our application example, we use a properties file as part of the web application resources: oidc.properties. We load the file and pass the options to the underlying framework.
In OIDC, Client and Relaying Party are interchangeable terms. Both refer to the ODIC application consuming IP services.
In JOSSO, RP properties are grouped in the following categories: Core, Registered URLs and Authentication. Below is the set of properties for each category.
Core Properties
Base RP information like identifier and RP authentication mechanism (not to be confused with user authentication).
| Property | Description |
|---|---|
| Base URL | Internal JOSSO base URL for services that the RP consumes. This value rarely needs to be updated. |
| Client ID | Unique identifier for the RP. It is one of two credentials used to authenticate the client. |
| Secret | Unique RP private password or key. It is used in combination with the client ID to authenticate the client. |
| Certificate (optinal) | Client certificate, only needed if Private Key client authentication is used. Provides an extra layer of security when authenticating the RP. |
| Client Authentication | Specifies how the RP will be authenticated by the IP: Client Secret HTTP Post , Client Secret HTTP Basic, Client Secret HTTP JWT or Private Key JWT |
Registered URLs
List of URLs that an RP can use when requesting services from the IDP. These are the URLs where a user is redirected after authentication and logout.
| Property | Description |
|---|---|
| Client URIs | A list of all valid URIs that the RP can use when requesting user authentication. The URIs are callback resources on the client side that can resolve the IP OIDC response. |
| Post Logout URIs | A list of all valid URIs that the RP can use when requesting a logout. |
Authentication
This is how the user identity will be established by the RP. It refers to the different authentication grants that OIDC supports.
| Property | Description |
|---|---|
| Grant type | It is the type of identity proof that the IP will send to the RP. The most common is Authorization Grant, but other options like SAML Assertion and JWT token are available. |
| Signing Algorithm | The digital signature mechanism to use when creating the identity token. |
| Encryption Algorithm | The encryption mechanism to use when creating the identity token. |
| Encryption Method | The encryption method to use when creating the identity token. |
Configure the Client Application
When configuring your OIDC client application, make sure that the settings applied to the RP element in the identity appliance match the values used in your OIDC framework. In particular, when selecting a secret, make sure that it is compatible with the selected signature and encryption options.
In our Java-based sample application, these are the properties used by the OIDC client. Any OIDC toolkit should support a similar set of options:
| Property | Description |
|---|---|
| oidc.authn.endpoint | This is the IP endpoint where the RP will request user authentication. The user is redirected to this URL. The value is dependent on your appliance configuration: https://<sso-server-name>/IDBUS/<id-appliance-uppercase>/<rp-name-uppercase>-OP/OIDC/AUTHZ/HTTP |
| oidc.token.endpoint | This is the IP endpoint where the RP will resolve tokens provided by the IP. The value is dependent on your appliance configuration: https://<sso-server-name>/IDBUS/<id-appliance-uppercase>/<ip-name-uppercase>-OP/OIDC/TOKEN/REST |
| oidc.authn.redirectUri | URL there the IP will redirect the user after authentication, so that the RP can resolve tokens. |
| oidc.client.id | RP identifier, same as configured in the RP element. |
| oidc.client.secret | RP private secret, same as configured in the RP element. |
| oidc.client.uri | One of the registered client URIs. |
| oidc.client.scopes | In this case the scope is always openid. |
| oidc.client.audience | This is the SAML entity ID for the IP as shown in the IdP element. |
oidc.properties
oidc.authn.endpoint=https://sso.mycompany.com/IDBUS/IDA-3/RP-1-OP/OIDC/AUTHZ/HTTP
oidc.token.endpoint=https://sso.mycompany.com/IDBUS/IDA-3/IDP-1/OIDC/TOKEN/REST
oidc.authn.redirectUri=https://app.mycompany.com/oidc-client/process-authz-code.jsp
oidc.client.id=369135750971-vumla38n2ue3ksevlo8rjdu8vf9j5his.apps.jossodev.tennis.com.au
oidc.client.secret=go0g1PMR9UOOTlUiNNZmb0Yc@35jh10A
oidc.client.uri=https://app.mycompany.com/
oidc.client.scopes=openid
oidc.client.audience=https://sso.mycompany.com/IDBUS/IDA-3/IDP-1/OIDC/MD
Resolving User Identity
Once your client is configured, you will be able to resolve the user identity after redirecting the user to the SSO authentication endpoint. With the received token you can obtain an ID Token and other information from the token endpoint.
The ID Token is a JSON Web Token (JWT) containing user information. The details on how to resolve the code depends largely on your toolkit. You can take a look at our sample code: process-authz-code.jsp
As you can see, the steps to process the IP reply with a code are:
Resolve the authorization code
Verify integrity and validity of the response
Decode information (ID Token, user claims)
Appendix A : Encryption and Signature
Signature Algorithms
Supported signature algorithms:
ES256 ECDSA using P-256 curve and SHA-256 hash algorithm (recommended).
ES384 ECDSA using P-384 curve and SHA-384 hash algorithm (optional).
ES512 ECDSA using P-521 curve and SHA-512 hash algorithm (optional).
HS256 HMAC using SHA-256 hash algorithm (required).
HS384 HMAC using SHA-384 hash algorithm (optional).
HS512 HMAC using SHA-512 hash algorithm (optional).
PS256 RSASSA-PSS using SHA-256 hash algorithm and MGF1 mask generation function with SHA-256 (optional).
PS384 RSASSA-PSS using SHA-384 hash algorithm and MGF1 mask generation function with SHA-384 (optional).
PS512 RSASSA-PSS using SHA-512 hash algorithm and MGF1 mask generation function with SHA-512 (optional).
RS256 RSASSA-PKCS-v1_5 using SHA-256 hash algorithm (recommended).
RS384 RSASSA-PKCS-v1_5 using SHA-384 hash algorithm (optional).
RS512 RSASSA-PKCS-v1_5 using SHA-512 hash algorithm (optional).
Encryption Algorithms
Supported encryption algorithms:
A128GCMKW AES in Galois/Counter Mode (GCM) (NIST.800-38D) 128 bit keys (optional).
A128KW Advanced Encryption Standard (AES) Key Wrap Algorithm (RFC 3394) using 128 bit keys (recommended).
A192GCMKW AES in Galois/Counter Mode (GCM) (NIST.800-38D) 192 bit keys (optional).
A192KW Advanced Encryption Standard (AES) Key Wrap Algorithm (RFC 3394) using 192 bit keys (optional).
A256GCMKW AES in Galois/Counter Mode (GCM) (NIST.800-38D) 256 bit keys (optional).
A256KW Advanced Encryption Standard (AES) Key Wrap Algorithm (RFC 3394) using 256 bit keys (recommended).
DIR Direct use of a shared symmetric key as the Content Encryption Key (CEK) for the block encryption step (rather than using the symmetric key to wrap the CEK) (recommended).
ECDH_ES Elliptic Curve Diffie-Hellman Ephemeral Static (RFC 6090) key agreement using the Concat KDF, as defined in section 5.8.1 of NIST.800-56A, with the agreed-upon key being used directly as the Content Encryption Key (CEK) (rather than being used to wrap the CEK) (recommended).
ECDH_ES_A128KW Elliptic Curve Diffie-Hellman Ephemeral Static key agreement per "ECDH-ES", but where the agreed-upon key is used to wrap the Content Encryption Key (CEK) with the "A128KW" function (rather than being used directly as the CEK) (recommended).
ECDH_ES_A192KW Elliptic Curve Diffie-Hellman Ephemeral Static key agreement per "ECDH-ES", but where the agreed-upon key is used to wrap the Content Encryption Key (CEK) with the "A192KW" function (rather than being used directly as the CEK) (optional).
ECDH_ES_A256KW Elliptic Curve Diffie-Hellman Ephemeral Static key agreement per "ECDH-ES", but where the agreed-upon key is used to wrap the Content Encryption Key (CEK) with the "A256KW" function (rather than being used directly as the CEK) (recommended).
PBES2_HS256_A128KW PBES2 (RFC 2898) with HMAC SHA-256 as the PRF and AES Key Wrap (RFC 3394) using 128 bit keys for the encryption scheme (optional).
PBES2_HS256_A192KW PBES2 (RFC 2898) with HMAC SHA-256 as the PRF and AES Key Wrap (RFC 3394) using 192 bit keys for the encryption scheme (optional).
PBES2_HS256_A256KW PBES2 (RFC 2898) with HMAC SHA-256 as the PRF and AES Key Wrap (RFC 3394) using 256 bit keys for the encryption scheme (optional).
RSA_OAEP RSAES using Optimal Assymetric Encryption Padding (OAEP) (RFC 3447), with the default parameters specified by RFC 3447 in section A.2.1 (recommended).
RSA1_5 RSAES-PKCS1-V1_5 (RFC 3447) (required).
Encryption Method
Supported encryption method:
A128CBC_HS256 AES_128_CBC_HMAC_SHA_256 authenticated encryption using a 256 bit key (required).
A128GCM AES in Galois/Counter Mode (GCM) (NIST.800-38D) using a 128 bit key (recommended).
A192CBC_HS384 AES_192_CBC_HMAC_SHA_384 authenticated encryption using a 384 bit key (optional).
A192GCM AES in Galois/Counter Mode (GCM) (NIST.800-38D) using a 192 bit key (optional).
A256CBC_HS512 AES_256_CBC_HMAC_SHA_512 authenticated encryption using a 512 bit key (required).
A256GCM AES in Galois/Counter Mode (GCM) (NIST.800-38D) using a 256 bit key (recommended).