Skip to main content

Applications

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

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

Under Applications, you have the following features to configure basic technical requirements for your applications:

Application list

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

Application list

Name

For each application, a unique Name is required.

The application Name has to be unique, and can contain alphanumeric characters and underscore only.

info

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

Application type

We support the following application types:

Single-page application

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

Applied technologies may include Angular, React, Vue.

These apps have to use Authorization Code with PKCE flow.

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

For SPA, the following parameters 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, 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

Single-page application

Regular web application

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

Applied technologies may include Java, .NET, PHP.

Web applications may use either the basic Authorization Code, or the more secure Authorization Code with PKCE flow.

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

In case of Protocol type OAuth 2.0/OIDC for WEB, the following parameters are used:

  • Client ID - generated by Identity Cloud
  • Client secret - generated by Identity Cloud
  • Allowed return URIs - one or more URIs, on a new line, that come from your application
  • 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 and authenticates the resource owner, 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

In case of Protocol type SAML for WEB, the following parameters are used:

note

For Subject, you need to choose between email or User ID. If you need a stable identifier which cannot change for the ID 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.

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

Regular web application with SAML

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 Refresh Token flow to request new tokens without user interaction.

For NAT, the following parameters are used:

  • Protocol type - set to OAuth 2.0/OIDC by Identity Cloud
  • Client ID - generated by Identity Cloud
  • Allowed return URIs - one or more URIs, on a new line, that come from your application
  • 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 and authenticates the resource owner, 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
Native application

Server to server application

Server-to-server (S2S) indicates either:

  1. a Resource Server which provides resources that can only be accessed with a valid Access token.
  2. a server-side application (e.g. a script) which uses Client Credentials flow to acquire an Access token to access a Resource Server.

For S2S, the following parameters are used:

Native application

ID

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

Add or edit an application

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.

Add application

For each application type, you need different parameters 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. We cannot save applications with missing mandatory parameters, so you have to add an application in one sitting.

To view or edit an already added application, just click on the application in the list.

In the Application settings tab of the application detailed view, you can edit the parameters of the application, with the same requirements when you added the application.

Detailed view of application

For information on the Permissions tab, see Permissions.

Application parameters

These are listed in alphabetical order below.

Access token lifetime

Access token lifetime defines how long access tokens issued by Identity Cloud are to be valid.

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 being used to retrieve a new access token and hence the harm that can be done is limited to the access token lifetime.

When an access token is expired, your app can get a new one by executing the Refresh Token flow, or the corresponding flow for the type of application:

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

Client ID

Client ID is the unique public identifier of your application.

Even though it is public, your application is more secure if the Client ID is not guessable by third parties, so we generate it for you to guarantee a higher level of security.

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 known by your application and the authorization server only. We randomly generate a Client secret for you that is up to security standards.

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

Endpoints

Authorization endpoint

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

Token endpoint

A client can obtain identity, access and refresh tokens from this endpoint.

Identity Cloud issuer

OAuth 2.0/OIDC

The Identity Cloud issuer is included as iss claim in Id tokens and Access tokens generated by Identity Cloud.

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

SAML

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 SP to validate the SAML response.

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

Identity Cloud signer certificate

OAuth 2.0/OIDC

Add the Identity Cloud signer certificate to the configuration of your SP to validate issued Id tokens.

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 SP to validate issued Id tokens.

SAML

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 SP to validate the signature.

Issuer

The SP uses the Issuer to validate SAML assertions.

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>test.use[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>

OpenID Connect service URL

OpenID Connect service URL is the URL of the OAuth 2.0 Authorization Server / OpenID Connect Provider.

Add the OpenID Connect service URL to the configuration of your SP to initiate authentication.

Protocol type

OAuth 2.0/OIDC

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.

SAML

SAML is an open standard that handles authentication flows between IdPs and SPs.

SAML improves user experience and increases security because the user only needs to sign in once to access several SPs.

Refresh token lifetime

Refresh token lifetime defines how long Refresh tokens shall be valid. To retrieve a new Access token after this time, the user has to log in again.

See also: Refresh Token

SSO service URL

SSO service URL is the URL of the SAML 2.0 IdP. 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 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 a HTTP POST or redirect.

Return URIs

ID Cloud uses these URIs to validate incoming requests according to the OAuth 2.0 specification and to return the code or token to. The user is redirected to the Return URI after successfully authorizing your application.

If the query parameter redirect_uri included in the request is allowed for this client and when authentication is performed, a code or token is returned to that URI, depending on what is returned in that flow.

This can be a classic URL, or a custom URL scheme that triggers a mobile application. The host name is required, and you can optionally also add the port. You can use both HTTP or HTTPS. The field allows multiple entries, each on a new line.

Example: https://your-company.com/callback

Tokens

You can adjust token lifetimes to suit your business needs. Shorter lifetimes increase security, longer lifetimes increase convenience. You need to set them to suit your customers.

Access token lifetime

Your Access token lifetime can be between one minute and one day. This token is used by the client to access the service, a resource server accessible via a REST API.

Id token lifetime

Your Id Token lifetime can be between one minute and one day. This token is used by the client as proof of authentication.

Refresh token lifetime

Your Refresh token lifetime can be between one day and 365 days. The Refresh token can be used to obtain new access and Id tokens without users having to reauthenticate.

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 the SP, or the SAML metadata file of the SP.

Managing Permissions

Using permissions, you can control what kind of rights different roles have in each application.

In the Permissions tab of the application detailed view, you have the following options to configure permissions:

In the permission list, all permissions associated with the application are listed. Permissions are ordered by last modified date.

The number of permissions is limited to 50 for each application. Each permission can belong only to the application for which the permission is created.

Permission list

Create or edit permission

Creating a permission in Identity Cloud is only half of the story.

  1. In Identity Cloud, you can only give the Name and a Description of the permission. This creates a custom permission, and what the permission does exactly depends on you. Permissions do not depend on protocols to give you flexibility in your definitions.
  2. In your system, you have to create the permission with the same name that you used in Identity Cloud. You define in your system what the permission lets the user do.
    info

    Identity Cloud has no way of checking if the permission Name given in Identity Cloud matches the permission name you used in your system. Make sure you double check for typos.

  3. Once the permission is created in both your system and in Identity Cloud, it comes alive. Assign the permission to a role, which is in turn assigned to a user.
  4. You can test if everything works as expected in the SAML or OAuth 2.0 response, depending on your application. Look for a string based on the OAuth claim preview or SAML assertion preview.
  5. If you click on the permission, you can edit the permission Name and Description with the same requirements. Keep in mind that the Name in Identity Cloud and in your system need to match for the permission to work.
Create permission

Name

The permission Name has to be unique, and can contain alphanumeric characters and underscore only. The length of the Name is maximum 30 characters. Although this is a restriction in Identity Cloud, keep this in mind when you create the permission in your system.

Description

Adding a Description is optional. If set, a good Description helps fellow admins identify what the permission does. The length of the Description is maximum 120 characters.

Delete permission

If you click on the permission, you can delete the permission after a confirmation.

info

Permissions come with a token. When you delete a permission, you revoke the token.

Permissions are deleted globally in Identity Cloud, that is, the permission is no longer connected to the corresponding application, or roles.

Deleting a permission in Identity Cloud also means that the connection between Identity Cloud and your system is broken for the permission. For a complete cleanup, delete the permission in your system as well.

Delete permission

If the permission in your system still exists, you can set up a working permission again by creating the permission in Identity Cloud with the same Name again.

Deleting an application

Deleting the application meant that the configuration is deleted from the database. Deletion is an irreversible action.

If you click on the application, you can delete the application after a confirmation.

Confirm deletion

Using Grant type flows

The following section summarizes what grant types are available for each application type. You can use any of the available types by default. The grant type is selected by the client by sending query parameter grant_type along with request. For the implementation, we are compliant with IETF RFC 6749 - The OAuth 2.0 Authorization Framework.

Application TypeAllowed Grant TypePKCE mode
APIclient_credentialsNot applicable
NATauthorization_coderequired
SPAauthorization_coderequired
WEBauthorization_codeallowed
note

Note: the grant type refresh_token is also allowed for NAT, SPA and WEB in order to request an Access token or Id token without requiring the user to reauthenticate.