Applications

In Applications, you can set up connections to your existing applications, depending on the protocols and technologies you use. The goal is for Identity Cloud to provide authentication and manage permissions for your applications.

The applications you add are the basis of any further configurations regarding Signup and Login flows and User management.

Under Applications, you have the following options to configure your applications and their OAuth2 / OIDC or SAML attributes:

View applications

The application list gives you a quick overview, where you can browse basic application data.

Name

For each application, a unique Name is required, which can contain maximum 30 alphanumeric characters and underscore.

info

We recommend you use a descriptive Name that you can easily remember throughout the configuration. You can use alphanumeric characters and the underscore.

Type

Identity Cloud supports the following Application types:

ID

ID is the unique identifier of the application, and is based on the following application attributes:

In case of Protocol type OAuth 2.0/OIDC, ID is based on Client ID.
In case of Protocol type SAML, ID is based on Issuer.

Add applications

Adding an application means that you set up a connection between your already existing application and Identity Cloud.

Go to Application management > Applications > Add application to set up the initial connection with basic application data.

We support the following application types:

Each application type needs different attributes for the configuration. The application wizard helps you in this process.

info

When you start adding an application, make sure you have all information with you. Applications with missing mandatory attributes cannot be saved.

Single-page application

Single-page application (SPA) indicates a JavaScript front-end application using an API.

Applied technologies may include Angular, React or Vue.

These apps have to use Authorization Code with PKCE flow.

Use the Refresh Token flow to request new tokens without user interaction.

The following attributes are used:

Protocol type - set to OAuth 2.0/OIDC by Identity Cloud
Client ID - generated by Identity Cloud
Allowed return URIs - you can register one or more allowed return URIs, each on a new line. The URIs define where the authorization server is allowed to redirect your users, back to your application after successful authentication.
Access token lifetime - you can define how long your access token is valid. Range from 1 minute to 1440 minutes (24 hours)
ID token lifetime - you can define how long your ID token is valid. Range from 1 minute to 1440 minutes (24 hours)
Refresh token lifetime - you can define how long your refresh token is valid. Range from 1 day to 365 days
Authorization endpoint - generated by Identity Cloud, the authorization server verifies the identity of the resource owner through authentication and returns an authorization code which can be exchanged for an access token at the token endpoint
Token endpoint - generated by Identity Cloud, the token endpoint provides the client with an access token. If requested, an ID token or a refresh token will be provided as well.
Identity Cloud issuer - generated by Identity Cloud.
Identity Cloud signer certificate - generated by Identity Cloud

Regular web application

Regular web application (WEB) indicates a traditional web application with most of the logic happening on the server side.

Applied technologies include Java, .NET or PHP.

For the Protocol type, you can choose between OAuth 2.0/OIDC and SAML. Select the one supported by your application.

OAuth 2.0 is an authorization framework that grants users access to a protected resource, to a third-party application or client. OIDC is an identity layer on top of OAuth 2.0, where clients obtain basic profile information about users.

Your application may use either the basic Authorization Code, or the more secure Authorization Code with PKCE flow. Use the Refresh Token flow to request new tokens without user interaction.

SAML is an open standard that handles authentication flows between Identity Providers and Service Providers (SP). SAML improves user experience and increases security because the user only needs to sign in once to access several SPs.

For more information on how Identity Cloud uses SAML, see SAML 2.0 endpoints.

In case of Protocol type OAuth 2.0/OIDC, the following attributes are used:

Client ID - generated by Identity Cloud
Client secret - generated by Identity Cloud
Allowed return URIs - you can register one or more allowed return URIs, each on a new line. The URIs define where the authorization server is allowed to redirect your users in your application after successful authentication.
Access token lifetime - you can define how long your access token is valid. Range from 1 minute to 1440 minutes (24 hours)
ID token lifetime - you can define how long your ID token is valid. Range from 1 minute to 1440 minutes (24 hours)
Refresh token lifetime - you can define how long your refresh token is valid. Range from 1 day to 365 days
Authorization endpoint - generated by Identity Cloud, the authorization server verifies the identity of the resource owner through authentication and returns an authorization code which can be exchanged for an access token at the token endpoint
Token endpoint - generated by Identity Cloud, the token endpoint provides the client with an access token. If requested, an ID token or a refresh token will be provided as well.
Identity Cloud issuer - generated by Identity Cloud
Identity Cloud signer certificate - generated by Identity Cloud

Regular web application with OAuth 2.0/OIDC

For SAML, the following attributes are used:

Issuer - comes from your application. The application uses this issuer for SAML messages sent to Identity Cloud.
Subject - define the format of the subject attribute in assertions. You need to use either Email, or User ID.
Outbound binding - use either a HTTP POST, or an HTTP redirect (302) leading to a GET.
Assertion Consumer Service URL - comes from your application
Audience - comes from your application, optional
X509 Signer Certificate - comes from your application, optional
SSO service URL - generated by Identity Cloud
Identity Cloud issuer - generated by Identity Cloud
Identity Cloud signer certificate - generated by Identity Cloud

note

For Subject, you need to choose between email or User ID. If you need a stable identifier that cannot change for the Identity Cloud user, choose User ID. As Subject is the permanent user ID for the entire user lifecycle, if you decide on email, it needs to remain the same and cannot be changed later on. You can only create a new user with a modified email address.

Native application

Native application (NAT) indicates an application stored on a mobile device or desktop, which runs natively.

Native apps have to use the Authorization Code with PKCE flow.

Use the Refresh Token flow to request new tokens without user interaction.

For NAT, the following attributes are used:

Protocol type - set to OAuth 2.0/OIDC by Identity Cloud
Client ID - generated by Identity Cloud
Allowed return URIs - you can register one or more allowed return URIs, each on a new line. The URIs define where the authorization server is allowed to redirect your users in your application after successful authentication.
Access token lifetime - you can define how long your access token is valid. Range from 1 minute to 1440 minutes (24 hours)
ID token lifetime - you can define how long your ID token is valid. Range from 1 minute to 1440 minutes (24 hours)
Refresh token lifetime - you can define how long your refresh token is valid. Range from 1 day to 365 days
Authorization endpoint - generated by Identity Cloud, the authorization server verifies the identity of the resource owner through authentication and returns an authorization code which can be exchanged for an access token at the token endpoint
Token endpoint - generated by Identity Cloud, the token endpoint provides the client with an access token. If requested, an ID token or a refresh token will be provided as well.
Identity Cloud issuer - generated by Identity Cloud
Identity Cloud signer certificate - generated by Identity Cloud

Server to server application

Server-to-server (S2S) indicates either a:

Resource Server which provides resources that can only be accessed with a valid access token.
Server-side application, for example a script, which uses a Client Credentials flow to acquire an access token to access a Resource Server.

The following attributes are used:

Protocol type - set to OAuth 2.0/OIDC by Identity Cloud
Client ID - generated by Identity Cloud
Client secret - generated by Identity Cloud
Access token lifetime - you can set the token lifetime between one minute and 1440 minutes, a day, to suit your users' needs.
Token endpoint - generated by Identity Cloud, the token endpoint provides the client with an access token.
Token introspection endpoint - generated by Identity Cloud, the Token introspection endpoint can be called by a resource server to validate received tokens.
Identity Cloud issuer - generated by Identity Cloud
Identity Cloud signer certificate - generated by Identity Cloud

Edit applications

To edit an application:

Go to Application management > Applications.
Select an application.
Click View more in the more options menu ︙ of the application.
On the Settings tab adapt any attribute of the application.
Click Save.

For information on the Permissions tab, see Configure permissions.

For information on the Scopes tab, see Configure allowed scopes.

Delete applications

You can delete an application from the application list or in the application details. Once confirmed, this operation cannot be undone.

To delete an application:

Go to Applications management > Applications.
Select an application.
Click Delete in the more options menu ︙ of the application.
In the dialog, confirm that you want to delete the application.
Click Delete.

info

If you delete an application, all permissions of the application will be deleted and all the allowed scopes will be removed.

OAuth2 / OIDC attributes

Access token lifetime

Access token lifetime defines how long access tokens issued by Identity Cloud need to be valid in the range of 1-1440 minutes. When an access token is expired, your app can get a new one by executing an appropriate flow:

Authorization Code - for classic Web applications. The user has to log in if there is no session on Identity Cloud.
Authorization Code with PKCE - for SPA and native apps. The user has to log in if there is no session on Identity Cloud.
Client Credentials - for server-side apps. No user interaction.
Refresh Token - for SPA, native and classic web applications. Requires a refresh token, but does not require user interaction.

note

Access tokens may be accepted by resource servers until expiration or revocation, even when the user has been blocked via the Identity Cloud management console in the meantime.

We recommend setting a short lifetime of a few minutes if you want to decrease the time a user can still access your services after being blocked. The benefit of having short-lived access tokens is that in case of a threat an admin can block a user, which prevents the refresh token flow from being used to retrieve a new access token, and hence the harm that can be done is limited to the access token lifetime.

Allowed return URIs

When an application initiates authentication by redirecting to the Identity Cloud authorization endpoint, it has to send along a query parameter redirect_uri that defines where to redirect the user after successful authentication.

This can be a classic URL or a custom scheme URI that triggers a mobile application.

Identity Cloud checks if the value sent in the redirect_uri parameter is allowed.

You can define multiple Allowed return URIs, each one on a new line. The hostname is required, and you can optionally add the port. You can use both HTTP or HTTPS.

For example: https://your-company.com/callback

Authorization endpoint

This endpoint can be used to request an authorization code by performing an end-user authentication. You can then exchange this code at the token endpoint for an access token.

Client ID

Client ID is the unique public identifier of your application. We generate your Client ID for you.

Client ID has a 16-character format, containing letters and numbers, according to "client_id" Syntax in The OAuth 2.0 Authorization Framework.

Client secret

Client secret is used by applications with a server-side component. Client secrets increase security as they are only known by your application and the authorization server. We generate a random Client secret for you.

Client secret has a 16-character format, containing letters and numbers, according to "client_secret" Syntax in The OAuth 2.0 Authorization Framework.

ID token lifetime

Set the lifetime of the ID token returned when the scope openid is requested. ID token lifetime need to be in the range of 1-1440 minutes.

Identity Cloud issuer

The Identity Cloud issuer is included as an Issuer Claim (iss) in ID tokens and access tokens generated by Identity Cloud.

Add the Identity Cloud issuer to the configuration of your resource servers to validate issued tokens.

Identity Cloud signer certificate

Access tokens and ID tokens are signed using a private key. Identity Cloud signer certificate is an X.509 certificate required to validate the signature.

Add the Identity Cloud signer certificate to the configuration of your resource server to validate issued tokens.

Refresh token lifetime

Refresh token lifetime defines how long refresh tokens are to be valid.

To retrieve a new access token after this time, the user has to log in again.

For more information, see Refresh token, which needs to be in the range of 1-365 days.

Return URI

The user is redirected to the Return URI after successfully authorizing your application. This can be a classic URL or a custom URL scheme that triggers a mobile application.

The hostname is required, and you can optionally add the port. You can use both HTTP or HTTPS.

For example: https://your-company.com/callback

Token endpoint

The token endpoint is used by the client to obtain an access token, by presenting its authorization grant or refresh token.

The token endpoint is used with every authorization grant.

Token introspection endpoint

Your resource server can use the token introspection endpoint to validate access tokens.

SAML attributes

Assertion Consumer Service URL

Assertion Consumer Service URL indicates the URL to which the SAML response is returned after successful authentication.

Audience

The application or the Service Provider (SP) verifies if Audience matches the recipient of a SAML response.

Audience has a URL format.

For example: https://sp.your-company.com/SAML

Identity Cloud issuer

Identity Cloud uses the value of Identity Cloud issuer for the Issuer in the SAML response.

Add Identity Cloud issuer to the configuration of your service provider to validate the SAML response.

For more information on how Identity Cloud uses SAML, see SAML 2.0 endpoints.

Identity Cloud signer certificate

Identity Cloud uses the Identity Cloud signer certificate to sign outgoing SAML messages, for example, the SAML response. Add the Identity Cloud signer certificate to the configuration of your service provider to validate the signature.

Issuer

The Service Provider uses the Issuer to validate SAML assertions. The Issuer needs to be unique and maximum 1024 characters.

In a SAML response, the Issuer contains the Entity ID of the Identity Provider (IdP) in a URL format.

In the following example, the Issuer is https://idcloud-customer.com:443.

<?xml version="1.0" encoding="UTF-8"?>
<saml2p:Response xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol" Destination="https://nevis-idc-poc.zendesk.com/access/saml" ID="Response_4198c277f78bdddc6407a4f000ecbb9bc736a21d" InResponseTo="samlr-646cc9ee-6181-11ec-8c71-9a44010eccb8" IssueInstant="2021-12-20T10:42:01.290Z" Version="2.0">
  <saml2:Issuer xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">https://idcloud-customer.com:443</saml2:Issuer>
  <saml2p:Status>
    <saml2p:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success" />
  </saml2p:Status>
  <saml2:Assertion xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:xs="http://www.w3.org/2001/XMLSchema" ID="Assertion_5095c848844fec0df9b41ba804d400a00b474b7c" IssueInstant="2021-12-20T10:42:01.287Z" Version="2.0">
    <saml2:Issuer>https://idcloud-customer.com:443</saml2:Issuer>
    <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
      <ds:SignedInfo>
        <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
        <ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256" />
        <ds:Reference URI="#Assertion_5095c848844fec0df9b41ba804d400a00b474b7c">
          <ds:Transforms>
            <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature" />
            <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">
              <ec:InclusiveNamespaces xmlns:ec="http://www.w3.org/2001/10/xml-exc-c14n#" PrefixList="xs" />
            </ds:Transform>
          </ds:Transforms>
          <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256" />
          <ds:DigestValue>UU/if6/6HlYrRS7rCTadVYAU1LuuHZEPI83lwSHdMZI=</ds:DigestValue>
        </ds:Reference>
      </ds:SignedInfo>
      <ds:SignatureValue>...</ds:SignatureValue>
      <ds:KeyInfo>
        <ds:X509Data>
          <ds:X509Certificate>...</ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
    </ds:Signature>
    <saml2:Subject>
      <saml2:NameID>[email protected]</saml2:NameID>
    </saml2:Subject>
    <saml2:Conditions NotBefore="2021-12-20T10:42:01.287Z" NotOnOrAfter="2021-12-20T10:43:01.287Z">
      <saml2:AudienceRestriction>
        <saml2:Audience>nevis-idc-poc.zendesk.com</saml2:Audience>
      </saml2:AudienceRestriction>
    </saml2:Conditions>
    <saml2:AttributeStatement>
      <saml2:Attribute Name="external_id">
        <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">372c3bbd-3e6b-44b5-baff-5ad33d199467</saml2:AttributeValue>
      </saml2:Attribute>
      <saml2:Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname">
        <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">User</saml2:AttributeValue>
      </saml2:Attribute>
      <saml2:Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname">
        <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">Test</saml2:AttributeValue>
      </saml2:Attribute>
    </saml2:AttributeStatement>
  </saml2:Assertion>
</saml2p:Response>

Outbound binding

Defines how SAML messages are returned to the initiating application.

Identity Cloud instructs the user agent (browser) to send the message to the Assertion Consumer Service URL.

You have the following options:

Post - uses a self-submitting form to send a POST. The message is included in the body.
Redirect - uses a 302 redirect to send a GET. The message is included as a query parameter.

As the differences are minimal you can choose what your service provider prefers.

SSO service URL

SSO service URL is the URL of the SAML 2.0 Identity Provider. Identity Cloud uses the same URL for all supported SAML 2.0 flows.

Configure the SSO service URL in your application or SAML 2.0 Service Provider (SP).

The SP initiates authentication by making the user agent (for example, browser) send a SAML authentication request (AuthnRequest) to the SSO service URL using HTTP POST or redirect.

Subject

Defines whether the User Id or the Email will be used in the Subject of the SAML Assertion.

Example for User Id:

<saml2:Subject>
    <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">eb363ae0-b2b2-4cc6-9e7b-36dcf84cd20c</saml2:NameID>
    <saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
        <saml2:SubjectConfirmationData NotOnOrAfter="2022-07-15T08:51:09.529Z"/>
    </saml2:SubjectConfirmation>
</saml2:Subject>

Example for Email:

<saml2:Subject>
    <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">[email protected]</saml2:NameID>
    <saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
        <saml2:SubjectConfirmationData NotOnOrAfter="2022-07-15T08:47:38.035Z"/>
    </saml2:SubjectConfirmation>
</saml2:Subject>

We recommend selecting User Id as this value never changes for a given user and does not expose the user email.

Select Email only if your service provider needs the user's email in the Subject.

X509 Signer Certificate

X509 Signer Certificate is needed if your SP signs the AuthnRequest.

X509 Signer Certificate has to be encoded in PEM format.

You can extract the certificate from the configuration of the Service Provider (SP), or the SAML metadata file of the SP.

Configure permissions

You can configure permissions of an application on the Permissions tab. For more information, see Permissions.

Configure allowed scopes

You can configure allowed scopes of an application of protocol type OAuth 2.0/OIDC on the Scopes tab. For more information, see Configure allowed scopes

Applications

View applications​

Name​

Type​

ID​

Add applications​

Single-page application​

Regular web application​

Native application​

Server to server application​

Edit applications​

Delete applications​

OAuth2 / OIDC attributes​

Access token lifetime​

Allowed return URIs​

Authorization endpoint​

Client ID​

Client secret​

ID token lifetime​

Identity Cloud issuer​

Identity Cloud signer certificate​

Refresh token lifetime​

Return URI​

Token endpoint​

Token introspection endpoint​

SAML attributes​

Assertion Consumer Service URL​

Audience​

Identity Cloud issuer​

Identity Cloud signer certificate​

Issuer​

Outbound binding​

SSO service URL​

Subject​

X509 Signer Certificate​

Configure permissions​

Configure allowed scopes​

View applications

Name

Type

ID

Add applications

Single-page application

Regular web application

Native application

Server to server application

Edit applications

Delete applications

OAuth2 / OIDC attributes

Access token lifetime

Allowed return URIs

Authorization endpoint

Client ID

Client secret

ID token lifetime

Identity Cloud issuer

Identity Cloud signer certificate

Refresh token lifetime

Return URI

Token endpoint

Token introspection endpoint

SAML attributes

Assertion Consumer Service URL

Audience

Identity Cloud issuer

Identity Cloud signer certificate

Issuer

Outbound binding

SSO service URL

Subject

X509 Signer Certificate

Configure permissions

Configure allowed scopes