Cloudentity Federation is a service that provides SSO (Single Sign On) for various types of disparate systems. It provides the interface for remote Identity Providers and Service Providers. Cloudentity Federation enables the mapping of external entity attributes to one which reflects a unified structure presented by Cloudentity.

Federation for External IDPs

Cloudentity external Identity Provider(IDP) federation services facilitates exchange of authentication and authorization information across different organizations with different security domains. Most common web security protocols that are supported in this service for exchanging security information with a third party Identity Provider are:

SAML( Security Assertion Markup Language)

SAML is an XML based language to exchange security assertions. SAML is an open standard that provides both authentication and authorization.

SAML defines following actors:

  • principal ⇒ end user trying to access a resource.

  • service provider ⇒ web resource that the principal is trying to access.

  • identity provider ⇒ server that holds the principal’s identities and credentials.

In this service, Cloudentity acts as the service provider to generate a SAML assertion request and consume the SAML assertion response from a third party identity provider and forward it to Cloudentity protected service or its own dashboard.

OpenID Connect

OpenID Connect is a simple identity layer on top of the OAuth 2.0 protocol, which allows computing clients to verify the identity of an 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 defines following actors:

  • End-User ⇒ entity for which we request identity information. In OAuth 2.0 terms, this is the resource owner, and the resource that he owns is his own identity.

  • OpenID Identity Provider (IDP or OP) ⇒ OAuth 2.0 authorization server that offers authentication as a service.

  • A Relying Party (RP) ⇒ OAuth 2.0 client that relies on the IDP in order to authenticate users and request claims.

In this service, Cloudentity acts as a relying party to initiate authentication with OpenID Identity Provider and consume the authentication response (ID Token along with claims).

1. Features

  1. SAML/OIDC Single Sign-on

SAML/OIDC Single Sign-on from external SAML enabled Identity Provider to Cloudentity Identity Platform allows authentication of users from external providers to access resources.

cloudentity federation external idp

  1. Just in time provisioning

Just in time provisioning of user accounts from external Identity Provider to Cloudentity Identity Platform

Cloudentity Federation microservice can consume a valid SAML response assertion and then transform the incoming assertion for the user identity onto various representations of Federated Identity in underlying Cloudentity Platform.

Just in time(JIT) provisioning of a federated user identity allows an organization to onboard limited set of user attributes from an external third party identity after authentication, Initial set of user profile data can be used to drive completion of the onboarding process , in case more business attributes are required for the profile). By default, all of the federated configurations between external Identity Providers will create a user account in underlying Cloudentity platform. This allows Cloudentity Platform to issue a single-sign on session for the federated Identity in Cloudentity system

  1. SAML assertion/OIDC attribue mapping

Map incoming SAML assertion/OIDC claim attributes to user account in Cloudentity Identity Platform

Cloudentity provides SAML Assertion/OIDC Claims attributes to be mapped to user attributes. Using federation management API’s each of the federation agreements can specify the incoming claim to a user record attribute name. Once this mapping established, any user that gets provisioned in Cloudentity platform will have these attributes mapped against their user record

  1. SAML assertion/OIDC permission mapping

Map incoming SAML attributes/OIDC claim to authorization entitlements/permissions in Cloudentity Identity Platform

Similar to above concept, advanced mapping is possible for mapping SAML assertions/OIDC claims to certain entitlements or permissions defined in Cloudentity System. This can be used for usecases wherein a group returned in SAML response assertion must map to a specific entitlement/permission in Cloudentity system. These entitlemetns/permissions can then be used for authorization enforcements by Cloudentity Authz engine.

  1. SAML completion workflows

Custom workflows after SAML Assertion/OIDC claim consumption from external Identity Provider

Organization may want to trigger separate workflow processes in addition to the default Cloudentity platform single sign-on after consuming a SAML assertion. This behaviour can be enabled defining a custom workflow provisioning endpoint during Idp registration.

2. Microservice Dependencies

Following microservices are required for Cloudentity external IDP federation services to function.

Cloudentity Federation

This microservice handles following functions * Generate SAML request assertion to external IDP * Consume SAML response assertion from external IDP * Generate OIDC request to external IDP * Consume OIDC claims from external IDP * JIT user in Cloudentity Identity Platform * Allow mapping/transforming SAML assertions/OIDC claims to User Attributes * Custom provisioning workflows after SAML/OIDC login process completion.

Component Name

orchis-federation

MicroService Type

SpringBoot(Java)

Containerized available

yes

Dependency type

direct
Federation management service

Federation Management Service is used to configure external Identity Provider information exchange metadata, trust and integration information. This will include information like metadata, attribute mapping rules, custom provisioner endpoints, status etc.

Component Name

federation-services

MicroService Type

Vertx(Scala)

Containerized available

yes

Dependency type

direct
Federation Management UI

Cloudentity provides an administrative panel to manage all the third party Identity Provider metadata and information exchange agreement at a per tenant Organization Level. (Refer to federation-admin-ui.adoc for more details)

Component Name

cloudentity-admin-ui

MicroService Type

NodeJs(Javascript)

Containerized available

yes

Dependency type

direct
Cloudentity Session Store

Cloudentity uses session store instance to share spring sessions for Cloudentity Federation microservice.

Component Name

orchis-session-store

MicroService Type

(Hazelcast)Java

Containerized available

yes( Not recommended)

Dependency type

direct
Cloudentity API GW

Cloudentity internal gateway to secure communication between internal services.

Component Name

orchis-api-gateway

MicroService Type

(Vertx)scala

Containerized available

yes

Dependency type

direct
Cloudentity LLA Service

Cloudentity uses low level abstraction as an abstracted level service for Federation management service to interact with underlying user data store and session store for JIT use case.

Component Name

orchis-lla

MicroService Type

(Tomcat)Java

Containerized available

yes

Dependency type

transitive
Cloudentity Identity Store

Dependency type: transitive

Cloudentity provisions user based on JIT settings to underlying Identity store. Cloudentity Identity Store can vary based on implementations and deployment architecture.

Third Party Components
Component Name Usage Required

Hazelcast

Used as implementation of Cloudentity Session Store

Optional (Required only for multi node architecture deployments)

supervisord

Used for process control for above microservices

Optional (Required only for non containerized deployments)

nginx

Used for routing and ssl to hit federation microservices

Optional (Required only for deployments that depends on nginx based routing)
Runtime dependency configuration
Component Name Configuration Configuration Details

Federation management service

External federated idp partner configuration

File: /opt/idam/orchis-federation/application.properties
Value: idpsConfig=http+jwt://192.168.66.6:7080/overlay/api/federation/idps?limit=999

Federation management service

Default workflow after SAML assertion is consumed

File: /opt/idam/orchis-federation/application.properties
Value: federation.authenticationServiceUrl=http://localhost:7080/overlay/api/federation/authentication/complete

Federation Management UI

Default redirect url after federation process is complete

File: /opt/idam/orchis-federation/application.properties
Value: federation.redirectionUrl=http://192.168.66.6

Cloudentity Session Store

Distributed session storage to store spring:sessions

File: /opt/idam/orchis-federation/hazelcast-client.xml

3. Configuration

Following steps needs to be done irrespective of any specific Identity Provider configuration to achieve SAML/OIDC integration.

3.1. Steps

  • Register Cloudentity in external IDP system as SP/RP/OIDC client etc [Commonly used IDP]

  • Obtain trust exchange information from external IDP

    • IDP SAML metadata (SAML)

    • OIDC credentials (OIDC)

  • Register external IDP in Cloudentity Identity Platform

  • Download Cloudentity SAML SP metadata generated per trust agreement(Required only for SAML)

  • Upload Cloudentity SAML Metadata to external IDP(Required only for SAML)

  • Verify External IDP based Single Sign On onto Cloudentity Identity Platform

Note
 Above outlined worklow is the default workflow. Workflows and redirects may be modified per Identity Provider configuration, using advanced settings within Cloudentity system based on custom business requirements.

Specific third party identity provider integration configuration are detailed in further sections.

3.2. Manage External Identity Provider

External Identity Provider configuration(metadata, attribute mapping) can be managed within Cloudentity can be done using either :

Important
 Only users with entitlements to manage IDP information can use administrative UI or API
Table 1. [IDP Configuration Fields]
Field Name Description Required Example

Name

A human readable name for the IDP agreement

Y

Salesforce IDP

Description

Description for the IDP agreement

N

Salesforce IDP agreement for east coast

Logo URL

Logo of the federated partner. This can be used to display in UI during authentication process. This needs to be in admin UI assets folder. Customizable during deployment time to include variety of logos based on deployment

Y

assets/images/idp/saml2.png

Metadata source

Location of IDP metadata agreement. It could be either provide as a URI or in XML format

Y

URI or XML data

Metadata source

Location of IDP metadata agreement. It could be either provide as a URI or in XML format

Y

URI

Metadata XML

This field needs to be provided if Metadata source is XML data. Need to be a valid SAML complaint agreement

N

SAML schema adherent to http://docs.oasis-open.org/security/saml/v2.0/saml-schema-metadata-2.0.xsd

Client ID

Client id obtained after registering CLoudentity as one of the OIDC assertion consumers in IDP. Each IDP will have different mechanism to register a consumer. Please refer to integration examples or contact IDP to get this client ID

Y

URI or XML data

Client Secret

Client secret obtained after registering CLoudentity as one of the OIDC assertion consumers in IDP. Each IDP will have different mechanism to register a consumer. Please refer to integration examples or contact IDP to get this client ID

Y

URI

Discovery URI

Endpoint for IDP url

N

SAML schema adherent to http://docs.oasis-open.org/security/saml/v2.0/saml-schema-metadata-2.0.xsd

Authentication lifetime

Timestamp for which the SAML assertion from third pary identity provider is considered to be valid. Beyond this time, SAML IDP needs to be provide a new assertion to Cloudentity.Time specified in seconds

N

3600

Custom provision URL

And endpoint to perform custom provisioning after SAML assertion is consumed. This endpoint must return a JSON payload back to Cloudentity system after the provisioning process. JSON payload must contain following structure

[source.json] ---- { "token" : "123-123-123" } ----

N

http://localhost:9080/do-something

Enabled

This IDP will be enabled only if this is selected for an active transaction. This allows an organization to selectively disable/enable IDP agreements

Y

Y

Visible

This indicates if the IDP agreement is visible outside organization, should be exposed for external public authentication etc

Y

Y

Field Mapping

This is a key to multi value mapping capability. This allows an incoming SAML assertion element to be mapped to multiple user attributes

Y

Y

Identifier field

One of the incoming SAML attribute can be used to correlate a record in Cloudenity system. Normally it could be any NameID element or element within SAML response assertion

Y

Y

Entitlements mapping

Provides capability to map specific data elements to grant specific entitlement to the user identity after the SAML assertion has been consumer

Y

Y

Permissions mapping

Provides capability to map specific data elements to grant specific entitlement to the user identity after the SAML/OIDC assertion has been consumed

Y

Y

Custom params

Provides capability to provide key value mapping pair. This can be used to map certain key values for specific custom integrations and using this during provisioning process of specific workflows.

Y

Y

3.3. Federation Management Admin User Interface

Cloudentity administrative UI application provides a simple user interface to manage external third party identity provider agreement and mapping information. Administrative users needs to have proper entitlement to act on specific actions. Each of these actions in UI are mapped directly to specific entitlements for user to allow fine grained access control of these operation from an administrative panel.

  • List Identity Providers

  • Get Identity Provider

  • Register Identity Provider

  • Update Identity Provider

  • Delete Identity Provider

List Identity Providers

User Entitlement: ADMIN_LIST_IDPS
Admin UI Location: Admin dashboard >> Identity Providers

List External Idps for Organization

Get Identity Provider

Entitlement: ADMIN_GET_IDP
Admin UI Location: Admin dashboard >> Identity Providers >> [Select one from list of Idps]

Get External Idp Configuration for Organization

Register Identity Provider

Entitlement: ADMIN_CREATE_IDP
Admin UI Location: Admin dashboard >> Identity Providers >> Register Identity Provider

For ease of registration of external third party identity providers, Cloudentity provides a list of templated providers to quickly create an agreement. In case you want to customize this list of templates, please refer to [customize-template.adoc] document

Idp Configuration Templates for Organization

You can either choose from a template or register a generic SAML or OIDC Identity Provider by clicking on the generic logos.

Register External Idp Configuration for Organization

Update Identity Provider

Entitlement: ADMIN_UPDATE_IDP
Admin UI Location: Admin dashboard >> Identity Providers >> [Select one from list of Idps] >> Update IDP

Update External Idp Configuration for Organization

Delete Identity Provider

Entitlement: ADMIN_DELETE_IDP
Admin UI Location: Admin dashboard >> Identity Providers >> [Select one from list of Idps] >> Delete IDP

Delete External Idp Configuration for Organization

3.4. Download Cloudentity SAML Metadata

Cloudentity SAML metadata information has to be provided to SAML enabled Identity Providers for registering Cloudentity as Service Provider.

Cloudentity metadata can be downloaded from Cloudentity System either via:

  • Administrative UI

idp download metadata

  • API Call

GET https://<cloudentity-federation-host>/federation/metadata/<registered-idp-hash>
Note
 Cloudentity SP metadata is available for download only after completion of external Identity Provider registration process within Cloudentity.
Tip
 Troubleshoot

3.4.1. Sample metadata

---
<?xml version="1.0" encoding="UTF-8"?>
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" ID="_la1yllgdzemh9ggyk1ipymrs1ljkummvwvcuwxw" entityID="urn:mace:saml:3b4ts14l0jveaad65c5a" validUntil="2037-05-23T04:56:21.422Z">
   <md:Extensions xmlns:alg="urn:oasis:names:tc:SAML:metadata:algsupport">
      <alg:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha512" />
      <alg:DigestMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#sha384" />
      <alg:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256" />
      <alg:DigestMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#sha224" />
      <alg:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
      <alg:DigestMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha512" />
      <alg:DigestMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha384" />
      <alg:DigestMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256" />
      <alg:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1" />
      <alg:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#dsa-sha1" />
   </md:Extensions>
   <md:SPSSODescriptor AuthnRequestsSigned="true" WantAssertionsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol urn:oasis:names:tc:SAML:1.0:protocol urn:oasis:names:tc:SAML:1.1:protocol">
      <md:Extensions xmlns:init="urn:oasis:names:tc:SAML:profiles:SSO:request-init">
         <init:RequestInitiator Binding="urn:oasis:names:tc:SAML:profiles:SSO:request-init" Location="http://federation.cloudentity.com/federation/callback?client_name=3b4ts14l0jveaad65c5a" />
      </md:Extensions>
      <md:KeyDescriptor use="signing">
         <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
            <ds:X509Data>
               <ds:X509Certificate>REPLACE_CE_IDP_X509_SIGNING_CERT</ds:X509Certificate>
            </ds:X509Data>
         </ds:KeyInfo>
      </md:KeyDescriptor>
      <md:KeyDescriptor use="encryption">
         <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
            <ds:X509Data>
               <ds:X509Certificate>REPLACE_CE_IDP_X509_ENCRYPTION_CERT</ds:X509Certificate>
            </ds:X509Data>
         </ds:KeyInfo>
      </md:KeyDescriptor>
      <md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:transient</md:NameIDFormat>
      <md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:persistent</md:NameIDFormat>
      <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat>
      <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat>
      <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="http://federation.cloudentity.com/federation/callback?client_name=3b4ts14l0jveaad65c5a" index="0" />
   </md:SPSSODescriptor>
</md:EntityDescriptor>
---
3.4.1.1. SAML Metadata terms
Name Description & Sample value

EntityID

Unique name representing the a federation agreement
entityID="urn:mace:saml:3b4ts14l0jveaad65c5a"

Assertion Consumer Url/ACS/Binding Url

SAML assertion listening endpoint. This value can be found within the Location block of AssertionConsumerService

<md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://federation.cloudentity.com/federation/callback?client_name=3b4ts14l0jveaad65c5a" index="0"/>

3.5. Verify SAML Authentication flow

  1. Initiate third party IDP authentication process using the unique identifier of the federation agreement.

GET
https://<cloudentity-federation-host>/federation/authenticate/<idp-identifier-hash>

  1. User will be redirected to external IDP to complete authentication process and on completion, user will be by redirected to Cloudentity self service profile page

3.6. SAML Debugging tools

There are several SAML browser tools available to trace SAML assertions for federations based on SAML.

Firefox:

Chrome

4. SAML Integration Examples

4.1. Salesforce

Salesforce can act as a single sign-on (SSO) identity provider to service providers, allowing end users to easily and securely access many web and mobile applications with one login. When using SAML for federated authentication, enable Salesforce as an identity provider and then set up connected apps. However, the OpenID Connect protocol for SSO authentication doesn’t require enabling Salesforce as an identity provider.

Salesforce IDP Documentation

Tip
 Contact your Salesforce administrators to ensure if your organization has Salesforce as IDP enabled.

  1. Login to Salesforce and set up Cloudentity platform as a connected app

sforce idp s01 click setup
sforce idp s02 search apps
sforce idp s03 new app
sforce idp s04 app basics
sforce idp s05 app saml
sforce idp s06 app save

  1. Fetch Salesforce SAML metadata

sforce idp s07 click manage
sforce idp s08 copy metadata url

  1. Register Salesforce as an external IDP in Cloudentity Learn more

  2. Download Cloudentity SAML SP metadata. Learn more

  3. Upload Cloudentity SAML Metadata to Salesforce Salesforce login >> Connected App >> Cloudentity Connected App >> Edit Polices

Instead of uploading metadata, Salesforce wants us to separately feed in information that is available within the metadata.Learn more about SAML Metadata fields.

sforce idp s13 click edit policies
sforce idp s14 add entityid

  1. Configure attributes that needs to be released in Salesforce

sforce idp s10 click manage profiles
sforce idp s11 add profiles
sforce idp s12 save profiles

  1. Verify SAML authentication flow with Okta. Learn more

4.2. Okta

4.2.1. 1. Register Okta as an external IDP in Cloudentity.

Click "Register Identity Provider" in "Identity Providers" on admin page.

okta idp s01 ce admin
Figure 1. Identity Providers page on admin dashboard

Click "SAML 2.0".

okta idp s02 register saml idp
Figure 2. Choosing IDP type

Put desired IDP name, description, Metadata Source, Authentication lifetime(in seconds).
Metadata Source can be chosen either as a URI or XML value.

Tip
 If "IDP Metadata Path" is unknown, put a dummy value for now (eg. http://localhost:1234)

Add Field mapping to map incoming SAML user entity to Cloudentity user attributes.

Table 2. Field Mapping
Incoming CE attribute

Email

uid

FirstName

firstName

LastName

lastName
okta idp s03 register saml idp2
Figure 3. Registering SAML 2.0 IDP

You now have successfully created an Identity Provider object.

4.2.2. 2. Set up a SAML SP application in Okta.

Set up a SAML SP application in Okta. Follow instructions on Okta SAML Documentation

You will need to reference created IDP details from Cloudentity admin page.

okta idp s04 idp details
Figure 4. IDP details view

For Single sign on URL on Okta SP, copy/paste Redirect URI from Cloudentity IDP.
Also, for Audience URI (SP Entity ID), copy/paste urn:mace:saml:<your IDP identifier here>.

okta idp s05 SAML settings
Figure 5. Okta SAML Settings

Configure IDP outbound field mapping.

okta idp s06 sp mapping
Figure 6. Okta IDP attribute mapping

After registering SAML SP application in Okta, download Okta Identity Provider Metadata.

okta idp s07 idp metadata
Figure 7. IDP Metadata
okta idp s08 idp metadataxml
Figure 8. IDP Metadata XML

Copy/paste the whole IDP metadata XML data to Cloudentity. Choose Metadata source equal to "XML data".

okta idp s09 upload idp metadata
Figure 9. Update IDP metadata source

You’re all set now. Verify SAML authentication flow with Okta. Learn more :imagesdir: img

4.3. Azure AD

This integration can be done in a Azure Active Directory that has following capability enabled.

Self-service integration of any application that supports SAML 2.0 identity providers (SP-initiated or IdP-initiated)
Tip
 Contact your Azure adminsitrators to ensure if your organization license for Azure has above capability enabled.

Azure AD IDP Documentation

  1. Configure Azure to Register Cloudentity as Service Provider*

NOTE : These might change as per Azure documentation

  • Login to Azure AD

  • Click on Azure Active Directory on left margin

azure idp a01 active directory

  • Click on Azure Active Directory on left margin

azure idp a02 enterprise apps

  • Register Cloudentity Platform as a new Non-gallery application

azure idp a03 new application
azure idp a04 non gallery
azure idp a05 enter name

  • Click on Azure Active Directory on left margin

azure idp a06 properties
azure idp a07 properties update

  • Enable Single sign on

azure idp a08 sso
azure idp a09 select saml

  1. Fetch Azure’s SAML metadata

azure idp a10 copy metadata url

  1. Register Azure as an external IDP in Cloudentity Learn more

  2. Download Cloudentity SAML SP metadata. Learn more

  3. Upload Cloudentity SAML Metadata to Azure

azure idp a10 upload metadata
azure idp a11 select file
azure idp a12 verify entityid
azure idp a13 sso save

  1. Configure attributes that needs to be released in Azure

    • Azure Active Directory >> App registrations

azure idp a13 click app registrations

  • App registrations >> View all

azure idp a14 click view all

  • Choose your application

azure idp a15 click application

  • Click Manifest

azure idp a16 click manifest

  • Look for groupMembershipClaims and change that value from null to "all"

Click Save

  1. Verify SAML authentication flow with Azure. Learn more

4.4. ADFS

ADFS Configuration screens may vary across different version of ADFS. Always refer to Relying party configuration section of ADFS Administration guide.

  1. Get ADFS SAML metadata

Normally ADFS metadata can be found in below url. Please check with ADFS administrators to confirm metadata URI before proceeding

https://CHANGEHOSTNAME/FederationMetadata/2007-06/FederationMetadata.xml

  1. Register ADFS as an external IDP in Cloudentity Learn more

  2. Download Cloudentity SAML SP metadata. Learn more

  3. Configure ADFS to register Cloudentity service as a SAML Relying Party using Cloudentity metadata

Server Manager >> Tools >> AD FS Management >> Actions >> Add Relaying Party Trust.

add relying party
Tip
 Once you pass the introduction page by clicking Start you will be given the option of how to enter data into ADFS. At this time ADFS cannot handle a URL with a query string, and so we will need to feed it our metadata manually. Click next to import the data.

  1. Configure attributes that needs to be released in ADFS

    • Edit Claim Rules dialog box, click Add Rule.

    • Use the default template to Send LDAP Attributes as Claims so click next.

    • Give the claim rule a descriptive name, and make sure the Active Directory Attribute Store is selected.

    • For the table below, the left will give you the AD attributes that you will need to select, and the outgoing claim type on the right.

release attribute

  • You must specify at least two attributes: Name ID and urn:oid:0.9.2342.19200300.100.1.1.

  • Once you are done, click Okay, and then OK to exit the edit claim rules dialog box.

  • You can return to it by right clicking the claim in the AD FS Management window.

  1. Verify SAML authentication flow with Okta. Learn more

4.5. Ping Federate

5. OIDC Integration Examples

5.1. Google OIDC

Cloudentity is able to connect to Google to provide authentication. This document describes Cloudentity Integration with Google working as external IDP. 

Setup

  1. Authenticate as admin. Register new Identity Provider using google template (provide dummy client id and secret, is active: true, is public: true). After creation save somewhere IDP hash, it should be sth like: cblfhdje2cekov09vjpp

  2. As a Google Developer go to https://console.developers.google.com to register new oauth client (application type: web application). 

Google Setup

  1. Add a authorized redirect URIs in form of: LOGIN_PAGE_URL/federation/callback?client_name=IDP_HASH, example: https://login.demo.orchis.syntegrity.com/federation/callback?client_name=jkh406jkd4l2n1m11m27. Save client id and client secret somewhere and click save.

Google Setup

  1. Go back to Cloudentity admin page and update Google IDP by providing client id and client secret from google developer console. Logout.

Verify

  1. Go to the login page and click on Google IDP icon

Google Setup

  1. Now you will be prompted to authenticate with google account

Google Setup
Google Setup

  1. Once authenticated you will be redirect to user self service

Google Setup

Mapping / Provisioning

There are two kinds of mapping available in IDP configuration in Cloudentity.

customMapping - defines which google idp attributes should be mapped to Cloudentity attributes while provisioning user.

"customMapping": {
    "sub": [
      "uid"
    ],
    "given_name": [
      "firstName"
    ],
    "family_name": [
      "lastName"
    ],
    "email": [
      "emails"
    ]
}

Orchis Federation oidc client is requesting following scopes: openid, profile, email when authorizing to Google IDP. Sample id_token payload is presented below:

{
  "azp": "1052752793169-vl42l884dc0d4478b97hbf8ipo6ntr0n.apps.googleusercontent.com",
  "aud": "1052752793169-vl42l884dc0d4478b97hbf8ipo6ntr0n.apps.googleusercontent.com",
  "sub": "115568505788082945315",
  "email": "ireneusz.kawalec.test@email.com",
  "email_verified": true,
  "at_hash": "ZLAOiBmI0jxq8Pr4dn2z6A",
  "exp": 1518431954,
  "iss": "https://accounts.google.com",
  "iat": 1518428354,
  "name": "Ireneusz Kawalec",
  "picture": "https://lh4.googleusercontent.com/-bUf-m7VbYNk/AAAAAAAAAAI/AAAAAAAAAAA/ACSILjVyAULbWY56_7D5tBr5X65qYxGhdw/s96-c/photo.jpg",
  "given_name": "Ireneusz",
  "family_name": "Kawalec",
  "locale": "en-GB"
}

entitlementMapping - optional mapping which allows to grant entitlements and entitlement groups to specific users. In the example below if user’s email in external IDP equals "ireneusz.kawalec.test@gmail.com" then on creation following entitlements and entitlementGroups will be granted to this user. 

"entitlementMapping": {
    "emails": {
      "ireneusz.kawalec.test@email.com": {
        "entitlements": [
          "TEST_ENTITLEMENT_1",
          "TEST_ENTITLEMENT_2"
        ],
        "entitlementGroups": [
          "TEST_ENTITLEMENT_GROUP_1"
        ]
      }
    }
}

Additionally while provisioning a new user in sla application.conf you in config: entitlements.newFederatedUser you can find a list of entitlements which by default will be granted to new users.

entitlements {
  newFederatedUser = ["SELF_GET_USER", "SELF_UPDATE_USER", "SELF_GET_CUSTOMER", "SELF_LIST_USER_CUSTOMERS"]
}

If you would like to use entitlementMapping you can use curl below (replace IDP_UUID and ADMIN_SESSION_TOKEN accordingly):

curl 'DEPLOYMENT_URL/ui/sla/federation/idps/IDP_UUID' -X PUT -H 'Content-Type: application/json' -H 'Accept: application/json, text/plain, */*' -H 'Cookie: token=ADMIN_SESSION_TOKEN' --data-binary '{
	"entitlementMapping": {
	    "emails": {
	      "ireneusz.kawalec.test@email.com": {
	        "entitlements": [
	          "TEST_ENTITLEMENT_1",
	          "TEST_ENTITLEMENT_2"
	        ]
	      }
	    }
  	}
}'

5.1.1. Troubleshooting

Download SP Metadata failure

Certificate used by the external federation IDP server URI(Only if IDP is registered using an external IDP metadata URI), is not a trusted certificate. If it is not trusted or self-signed, then the certificate needs to be added in the java certificate keystore.

Sample import example:

idam$ keytool -import -alias startcom -file /tmp/1_root_bundle.crt -keystore jdk-8u40/jre/lib/security/cacerts

You will be asked to trust the certificate.
Confirm, and then restart the orchis-federation process