Create an App
By default there are no Apps configured when a Tenant is created. Creating an App is simple and involves only a couple of steps. Some configuration parameters depend on the type of App and the technology/protocol used to connect the App to The Identity Hub.
- Navigate to the Apps Admin Page (https://www.theidentityhub.com/{tenant}/Admin/App) of your Tenant and click on Add. If you don't have a Tenant yet, you can register one for free.
- Type a Name and Description for the App.
- Depending on the type of application and the technology/protocol used to connect the application to The Identity Hub you will have to supply one or more configuration parameters.
- Click Save.
General configuration parameters
| Parameter | Description |
|---|---|
| Name | Display name of the application. |
| Description | Description of the application. |
| This app is under your control | Indicates if this is an application from an external party or not. |
| Native app (Mobile or desktop) | Check this to indicate the app can use a custom scheme for redirect URI's |
| Logo | An optional logo for the application. |
| Custom logon result URL's (on Edit only) | When the authentication fails a user can be redirected to a custom URL depending on the specific outcome: - Access denied: The responding provider has chosen not to authenticate the user. - Failed: The responding provider was unable to successfully authenticate the user. - An error occurred: Another error occurred during the authentication process Example URL: https://www.myaccessdeniedurl.com |
| Additional information (on Edit only) | Informative field to provide some additional information regarding the app (e.g. contact info of the app owner(s)). |
OAuth 2.0
For more information on the OAuth 2.0 authorization framework see https://tools.ietf.org/html/rfc6749
| Parameter | Description |
|---|---|
| Token life time | The number of hours and minutes the OAuth Access Token is valid for this application. |
| Refresh Token life time | The number of days, hours and minutes the OAuth Refresh Token is valid for this application. When setting the refresh token lifetime to 0 it expires immediately and thus prevents exchanging it for a new access token. |
| Redirection URI's | Valid OAuth redirect URI's. http://localhost and https://localhost are supported out-of-the-box. custom schemes are allowed for native apps. |
| Confidential | If checked the client_secret must be specified for the OAuth 2.0 Authorization Code and Refresh Token flow. |
| Force Proof Key for Code Exchange (PKCE) | To force the usage of PKCE in the OAuth 2.0 Authorization Code flow. See https://tools.ietf.org/html/rfc7636 |
Warning
As refresh tokens have the potential for a long lifetime, application developers should ensure that they are stored under strict storage to keep them from being leaked.
Note
When editing the lifetime of the tokens for an existing app the issued access tokens and/or refresh tokens are not updated accordingly.
OpenID Connect
For more information on the OpenID Connect see https://openid.net/connect/
All parameters of OAuth 2.0 apply to OpenID Connect. Specific OpenID Connect parameters are listed below.
| Parameter | Description |
|---|---|
| OpenID Connect ID Token Encryption Certificate | The certificate used to encrypt the OpenID ID tokens. (See App Certificates parameters) |
| OpenID Connect JWT Token Signing Certificate | The certificate used to sign OpenID Connect tokens. (See App Certificates parameters) |
WS-Federation
For more information on WS-Federation see http://docs.oasis-open.org/wsfed/federation/v1.2/ws-federation.html.
| Parameter | Description |
|---|---|
| Relying Party Realm | Unique URI for the application. |
| WS-Federation Reply URL's | Valid reply URLs. |
| Relying Party Certificate | The certificate used to encrypt the tokens sent to the application. (See App Certificates parameters) |
| Token Signing Certificate | The certificate used to sign the tokens sent to the application. (See App Certificates parameters) |
| Secure Hash Algorithm | The hash algorithm used to sign and encrypt.(See App Certificates parameters) |
SAML-P
For more information on SAML-P see https://wiki.oasis-open.org/security/FrontPage.
| Parameter | Description |
|---|---|
| Issuer | Unique URI for the application. |
| Service Provider Certificate | The certificate used to encrypt Authentication Responses and Assertions sent to the application. The certificate used by the application to sign Authentication Requests. (See App Certificates parameters) |
| Data Encryption method | The encryption method for encrypting the data (default = AES256). |
| Key Encryption method | The encryption method for encrypting the symmetric key (default = RSA15). |
| Identity Provider Certificate | The certificate used to sign the Authentication Response sent to the application. (See App Certificates parameters) |
| Secure Hash Algorithm | The hash algorithm used to sign and encrypt.(See App Certificates parameters) |
| SAML-P Assertion Consumer Endpoints | Assertion consumer endpoints of the application. Supported binding type is Http-Post. |
| Single Log Out Response URL | The Single Log Out Response URL to use. |
| Single Log Out Endpoint Protocol Binding | Supported binding types are Http-Post and Http-Redirect. |
App Certificates
These are certificates used by specific protocols. The usage of the certificates varies with the protocol.
See specific OpenID Connect, SAML-P and WS-Federation parameters.
For the Signing certificate it is possible to opt to use the certificate stored at tenant level, or to upload one specifically to the app.
When all apps are under your control and replacing the certificate can easily be planned and executed on one specific moment it is easier to let apps use the tenant signing certificate and replace it in one single go.
If however apps for a tenant are maintained by different external parties, it might be beneficial to let apps use a certificate specified at their own level in order to smoothen replacing the certificate app by app.
See Used Certificates Overview to get an overview on the impact.
Output Claims
Information (claims) of the user that logs on is passed to the application. The output claims determine what information is available to the application and can also map some information to another claim type if this is required by the application.
Depending on the protocol used to connect the application to The Identity Hub, the information (claims) are passed in different manners (either within the token or as assertions in the response).
Some of the claims are always sent to the application, some are optional.
Most claims can also be set as required by the application. This means that a user will only gain access to the application when the required claim is present. If not present, the user will not be redirected to the app but instead land on a page informing there are missing claims.
A possible candidate is for instance the emailaddress of an identity. In case your application requires a manner of getting in touch with the user you can opt to set this Standard Output Claim as required.
See the list of Standard Output Claims below to know which claims are required by default.
Standard Output Claims
These are the claim types that are out of the box available.
- By default available for the application: The claim is always available for an App if the user has the information that is resembled in the claim.
- By default Required: The claim is always required before a user can authenticate for an App. Authenticated users always have this claim.
- Can be set as Required: Indication if the claim can be set as required when a user authenticates for an App. If this option is set, the user needs to have the information that is resembled in the claim.
- In token/assertion: Some protocols (like Open ID Connect/SAMLP/WSFED) can send user info in the token/assertion that is the result of the authentication flow. This setting can be used to determine if the info is contained in the token/assertion.
Note
* As of version 1.61.0.0 The Identity Hub allows to configure the role claim as required.
If so, the user will need to have at least one of the related roles for the application before being redirected to the application
See Roles for App
Optional Output Claims
These are claim types that can be set as available and/or set as Required.
There are two types:
- Mapping Claims: Claims that are mapped to a specific output claim type.
- From Account Providers: Claims that are provided by the Account Providers.
Mapping Claims
From Account Providers and Claim Providers
| Claim type | Available for the application | Can be set as Required | In token/assertion |
|---|---|---|---|
| Depends on the claim types made available by the Account Providers and Claim Providers | Configurable | Yes | Configurable |
- Can be set as Required: Indication if the claim can be set as required when a user authenticates for an App. If this option is set, the user needs to have the information that is resembled in the claim. In case of the role claim at least one role for the related App should be present.
- In token/assertion: Some protocols (like Open ID Connect/SAMLP/WSFED) can send user info in the token/assertion that is the result of the authentication flow. This setting can be used to determine if the info is contained in the token/assertion.
OpenID Connect UserInfo endpoint
By default only claims set as Available for the application AND In token/assertion are returned by the UserInfo endpoint.
However the following claims are always returned regardless of the configuration, based on the following mapping:
To retrieve information that is not available using the UserInfo endpoint use the Introspection endpoint.
OAuth Introspection endpoint
According to the RFC the only required information in the response for the Introspection endpoint is the "active" property.
Next to this, additional information to be sent to apps can be configured.
By default only claims set as Available for the application are returned by the Introspection endpoint. They are added to the Properties array within the JSON result unless they are part of the below mapping.
However the following claims are always returned regardless of the configuration, based on the following mapping:
Related
OAuth 2.0 Endpoints
OpenID Connect Endpoint - UserInfo
SAML-P Endpoints