Identity Providers

Identity Provider is the term used to describe any mechanism or system that handles authentication of users, and provides claims about those users to CFS. There are five types of identity providers / authentication systems supported in CFS:

• Login / Password Authentication (Forms Based Authentication)
• Certificate/PIV card Authentication
• Social Networks
  • Facebook
  • GitHub
  • Google
  • Instagram
  • LinkedIn
  • Microsoft(Azure Active Directory)
  • PayPal
  • Twitter
  • WordPress
  • Yahoo
• Active Directory (RadiantOne Trust Connectors)
• External Trusted Identity Providers
  • Microsoft AD FS
  • OpenAM
  • RSA SecurID (deprecated)
  • Other Ws-Federation Identity Providers...

Below is a high-level diagram depicting the flow when CFS leverages a Trusted Identity Provider for authentication. In scenarios like this, CFS acts as a relying party to the Trusted Identity Provider. This is known as Inbound Federation. CFS is receiving assertions from a trusted IDP to provide access to identities outside of CFS's security boundary to relying parties that trust CFS as their Identity Provider.

In environments where an existing identity provider is deployed and needs to trust CFS as an identity/claims provider, the existing identity provider is then considered a relying party for CFS. This is known as Outbound Federation. CFS produces the assertions to be consumed by a trusted IDP. This allows identities managed by CFS to access applications outside of its security boundary. This is depicted in the diagram below.

Applications

Smart links

For RP-initiated SSO (when a user navigates directly to a site/application) the Identity Provider (IDP) knows exactly where to redirect the user back to after they authenticate. However, for IDP-initiated SSO (when the user navigates directly to the IDP to log in first), the exact desired application/sub-service may not be known so CFS would redirect the user back to a general/main page of the service instead of directly to the sub-service.

Smart Links provide users with an improved login experience when accessing any browser based site that offers many services/sub-sites. An example is Office 365 which offers many services, including SharePoint Online. Even SharePoint 2010 (on-premise) offers many different sites/web applications. Another example is Google Apps which offers many services like email, calendar...etc.

Smart Links offer an improved IDP-initiated user experience because once logged in, with just a single click, the user is automatically redirected to the specific service without any additional clicks required.

On the CFS configuration side, only 1 application is required to be configured. Then each sub-service is configured for this application as a smart link.

This page explains the Smart Link generation and deployment process in detail and is based on a use case of Office 365 (SharePoint Online) deployed trusting ADFS as the Identity Provider and extending access to users in CFS (ADFS configured with a claims provider trust for CFS).

• Install Fiddler.
• Open Fiddler and enable HTTPS decryption.
• Open Internet Explorer, clear the cookies and restart the browser.
• Using Internet Explorer, navigate to an Office 365 SharePoint site.
• At the Office 365 Login Prompt, enter your username, check the boxes ‘Remember me’ and Keep me signed in’ and then click "Sign in at ".
• Return to Fiddler and locate the 302 redirection session. Right-click the 302 session, click "Copy and click "Just Url".
• Open Notepad and paste the string copied in step 6. It should look something like:

[https://federation.domain.com/adfs/ls/?cbcxt=mai&vv=&username=david.ross%40domain.com.au&mkt=&lc=3081&wa=wsignin1.0&amp](https://federation.domain.com/adfs/ls/?cbcxt=mai&vv=&username=david.ross%40domain.com.au&mkt=&lc=3081&wa=wsignin1.0&amp); wtrealm=urn:federation:MicrosoftOnline&wctx=MEST%3D0%26LoginOptions%3D1%26wa%3D wsignin1%252E0%26rpsnv%3D2%26ct%3D1348618157%26rver%3D6%252E1%252E6206%252 E0%26wp%3DMBI%26wreply%3Dhttps%253A%252F%252Fdomain%252Esharepoint%252Ecom %252F%255Fforms%252Fdefault%252Easpx%26lc%3D3081%26id%3D500046%26cbcxt%3Dmai %26wlidp%3D1%26guest%3D1%26bk%3D1348618158

• Remove everything between ".../adfs/ls/?" and "wa=wsignin...", and everything after "...wreply%3D". The string now looks like:

[https://federation.domain.com/adfs/ls/?wa=wsignin1.0&wtrealm=urn:federation:Microsoft](https://federation.domain.com/adfs/ls/?wa=wsignin1.0&wtrealm=urn:federation:Microsoft) Online&wctx=MEST%3D0%26LoginOptions%3D1%26wa%3Dwsignin1%252E0%26rpsnv%3D2 %26ct%3D1348618157%26rver%3D6%252E1%252E6206%252E0%26wp%3DMBI%26wreply%3D

This is the base URL that is used to create the Smart Links.

Next, convert the SharePoint site URLs to double encoded URLs. We need to do this for all SharePoint sites that you would like to create Smart Links for. Use the following table as a reference:

ASCII Character Double-Encoded Value
: %253A
. %252E
/ %252F

The following are some examples of URLs and their double-encoded URL equivalent:

URL -- > Double-Encoded URL https://company.sharepoint.com -- > https%253A%252F%252Fcompany%252Esharepoint%252Ecom https://company.sharepoint.com/search -- > https%253A%252F%252Fcompany%252Esharepoint%252Ecom%252Fsearch https://company-10.sharepoint.com/sites/finance -- > https%253A%252F%252Fcompany-10%252Esharepoint%252Ecom%252Fsites%252Ffinance

• To complete the Smart Link, append the double encoded string to the base URL that was previously created. The end result is a Smart Link that looks something like:

[https://federation.domain.com/adfs/ls/?wa=wsignin1.0&wtrealm=urn:federation:Microsoft](https://federation.domain.com/adfs/ls/?wa=wsignin1.0&wtrealm=urn:federation:Microsoft) Online&wctx=MEST%3D0%26LoginOptions%3D1%26wa%3Dwsignin1%252E0%26rpsnv%3D2% 26ct%3D1348618157%26rver%3D6%252E1%252E6206%252E0%26wp%3DMBI%26wreply%3D https%253A%252F%252Fcompany%252Esharepoint%252Ecom

The URL generated in the previous section is used during the CFS configuration described below.

• From the Tenant Administration Dashboard, navigate to the Applications sections.
• Click Gallery and click Configure next to the application you want to configure with Smart Links. (This example uses ADFS as WS-Federation).
• Enter the needed parameters (if you need assistance, see Applications ).
• Click Smart Links at the bottom of the page.
• Click New Smart Links.
• Paste in the final smart link result calculated in the previous section. E.g. [https://federation.domain.com/adfs/ls/?wa=wsignin1.0&wtrealm=urn:federation:Microsoft](https://federation.domain.com/adfs/ls/?wa=wsignin1.0&wtrealm=urn:federation:Microsoft) Online&wctx=MEST%3D0%26LoginOptions%3D1%26wa%3Dwsignin1%252E0%26rpsnv%3D2% 26ct%3D1348618157%26rver%3D6%252E1%252E6206%252E0%26wp%3DMBI%26wreply%3D https%253A%252F%252Fcompany%252Esharepoint%252Ecom
• Toggle the "Is Enabled" option so that is shows a green check mark.
• Enter any other desired parameters on the General, Access Rules and Filter tabs and then click Save. For details on parameters available on these tabs, please see the Applications Configuration guide.

OpenID Connect

CFS supports OAuth 2.0 and is an OpenID Connect provider. It supports the role of "Authorization Server" (to authenticate users) and "Resource Server" (to deliver user attributes requested by the application).

When a user accesses the OpenID Connect application (relying party), they are redirected to the "authorization endpoint" of CFS to authenticate (step 2 in the diagram below). If the user has an active session with the CFS, authentication may be skipped.

After the user authenticates to CFS, they are prompted to authorize the application to access certain profile information (unless they've already given permission to the application previously, in which case they are not prompted). This is shown in step 3 in the diagram below.

The user browser is sent back to the client application (indicated by the Callback URL in the configuration) with the authentication/authorization result (shown in step 4 in the diagram below). The application can contact CFS (DIRECTLY) at the UserInfo endpoint (shown in step 5 in the diagram below). The application has a maximum of 2 minutes to contact CFS for the user's information. After 2 minutes, the access token is no longer valid and steps 2-4 shown in the diagram must be done again. Note here that even if steps 2-4 is executed again, the user does not see any of this because they have already been authenticated by CFS (and not prompted again) and already authorized the application to access their information (so they won't have to consent again - as long as they have not manually revoked access to this application in the meantime). The UserInfo endpoint (CFS) returns consented profile information to the client application (shown in step 6 in the diagram below). This can contain ONLY attributes indicated in the "scope" (indicated in the Mappings).

A tenant's OIDC discovery document is located at:

https://cfs-server.domain.com/cfs/oauth/[tenant-identifier]/.well-known/openid-configuration

This discovery document provides general information about the OpenID connect configuration such as:

• The OAuth issuer (CFS tenant)
• Authorization endpoint
• Token endpoint
• User Information endpoint
• Response types and response modes supported
• ID token Signing algorthims supported
• The JSON Web Keys URI
• Supported scopes
• End session endpoint and check session iframe

A few things to keep in mind for OpenID Connect Applications are:

• There are no certificates required.
• The application can communicate directly to CFS to get information about a user (not just indirectly through the client browser with redirects).
• Only RP-initiated SSO is supported (no IDP-initiated, which means OpenID Connect applications does not appear in the CFS portal).

Supported Flows in CFS

The following OIDC flows are supported:

• Authorization Code
• Authorization Code (with PKCE)
• Hybrid
  • code token
  • code id_token
  • code id_token token
• Implicit
  • id_token token
  • token
  • id_token

Tokens in CFS are returned in the form of Json Web Tokens (JWTs).

Access Tokens

An access token body returned from CFS looks similar to:

{
    "name": "Jane Doe",
    "sub": "Jane Doe",
    "scope": "openid profile address phone email",
    "token_type": "bearer",
    "client_id": "h5Ik8ep4nFMu433hUI55g",
    "nbf": 1610573741,
    "exp": 1610573861,
    "iat": 1610573741,
    "iss": "https://cfs.server/cfs/oauth/[tenantIdentifier]",
    "aud": "https://cfs.server/cfs/oauth/[tenantIdentifier]"
}

These access tokens have a two minute expiration time, unless changed in the tenant admin console.

Important things to note:

• The "aud" (Audience) claim is the resource the access token is intended for. In this case, it's CFS which, as mentioned above, is also the resource server.
• The "iss" (Issuer) claim is who issued the access token (the authorization server), which is also CFS.
• The "scope" claim are those user claims that the OIDC client is requesting from the backend datastore (FID).

ID Tokens

An ID token body returned from CFS looks similar to:

{
    "name": "Jane Doe",
    "sub": "Jane Doe",
    "family_name": "Doe",
    "given_name": "Jane",
    "nickname": "jen",
    "gender": "female",
    "address": "123 East Brussels Lane, Novato, CA 95213",
    "email": "[email protected]",
    "email_verified": "True",
    "phone_number": "555-639-1234",
    "phone_number_verified": "False",
    "nonce": "63746170493LWE2NzQtNTdkMGQ3Zjc5NjU2",
    "at_hash": "UBugsfdT1PWxJ6wqpw",
    "c_hash": "Upb8pdndf30UQ4-g",
    "nbf": 1610573742,
    "exp": 1610574942,
    "iat": 1610573742,
    "iss": "https://cfs.server/cfs/oauth/[tenantIdentifier]",
    "aud": "h5Ik8ep4nFMu433hUI55g"
}

These ID tokens have a twenty minute expiration time, unless changed in the tenant admin console..

Important things to note:

• The "aud" (Audience) claim is the OIDC client the token is intented
• The "iss" (Issuer) claim is the authorization server that issued the ID token, which is CFS.
• The "c_hash" (Code Hash) value is included in the ID token if the response_type includes a code (i.e code, code id_token, code token id_token).
• The "at_hash" (Acess Token Hash) value is included in the ID token if the response_type also includes an access token (i.e code id_token token).
• Requests to the authorize endpoint that contain any of the below response types return user claims only from the /userinfo endpoint:
  • token
  • code token
  • token id_token
  • code id_token token

These tokens are signed using JSON Web Keys (JWKs). The key ID (kid) used to sign the token can be found in the JSON Web Token's header

{
    "alg": "RS256",
    "kid": "9ac7441d-1c47-49ad-9bb9-740d0f6a1702",
    "typ": "JWT"
}

The JWKs can be accessed from https://cfs-server.domain.com/cfs/oauth/[tenant-identifier]/.well-known/keys. This endpoint can be discovered from tenant's OIDC discovery document.

Keys are automatically rotated every 180 days.

There are two parts to the configuration in CFS. One is the configuration of the application. The other is configuring which identity store attributes are associated with the scopes (mappings). These configurations are described below.

Application

In the Tenant Administration Dashboard, navigate to the Applications section and select OpenID Connect. Click New OpenID Connect Application.

1. Enter a unique name for the OpenID Connect application.
2. Enter a description.
3. Enter a website associated with the application.
4. Enter a Callback URL. The address where CFS redirects the user to after authentication.
5. Enter the organization name and website. This information is displayed to the user (along with the logo you configure in the next step) when requesting consent for the application to access the user's information.
6. Select a logo to display to the user when requesting consent for the application to access the user's information.
7. Check "Is Enabled" until it shows green.
8. Take note of the Application Key and Secret as this information is used in the configuration of the application (when you set it up to be able to connect to CFS).

Mappings (Scopes)

OpenID Connect "scopes" can be thought of as predefined sets of claims/assertions. To define the attributes associated with the scopes, from the Tenant Administration Dashboard, navigate to Applications and select OpenID Connect. Click Mappings.

Profile Scope

The “profile” scope is equivalent to requesting the following claims/assertion:

• name
• family_name (Last Name)
• given_name (First Name)
• middle_name, Nickname
• peferred_username
• profile
• picture
• website
• gender
• birthdate
• zoneinfo
• locale
• update_at

You can indicate which attribute from the identity store (FID) should populate each claim.

Email Scope

The "email" scope is equivalent to requesting the Email claim/assertion. You can indicate which attribute from the identity store (FID) should populate this claim (e.g. mail). There is an option to indicate that emails are verified in the identity store. Neither CFS nor FID perform any verification of this value. When the identity store (FID) is configured, this attribute can be deemed "verified" by the administrator (when configuring FID, you can indicate which data source is authoritative for this information). If the attribute is considered verified, toggle the switch to green/on next to "The emails are verified in the identity store".

Address Scope

The "address" scope is equivalent to requesting the Address claim/assertion. You can indicate which attribute from the identity store (FID) should populate this claim (e.g. postalAddress).

Phone Scope

The "phone" scope is equivalent to requesting the Phone Number claim/assertion. You can indicate which attribute from the identity store (FID) should populate this claim (e.g. mobile). There is an option to indicate that telephone numbers are verified in the identity store. Neither CFS nor FID perform any verification of this value. When the identity store (FID) is configured, this attribute can be deemed "verified" by the administrator (when configuring FID, you can indicate which data source is authoritative for this information). If the attribute is considered verified, toggle the switch to green/on next to "The phone numbers are verified in the identity store".

Groups Gcope

The "groups" scope is the equivalent to requesting a special groups assertion, which retrieves the groups a user is a part of. The group attribute is determined based on the tenant's group schema as seen below.

Custom Claims

CFS supports configuring custom claims. These custom claims are returned as part of the profile scope. If a custom claim is disabled, it is not returned in either the id_token or from the /userinfo endpoint. Custom claims, like all other scopes, can only be managed by tenant administrators. To add a custom claim:

1. From the Administration tab navigate to Applications > OpenID Connect

2. In the top right, click + Add Custom Profile Scope Claim

   

3. In the popup that appears, enter a Claim name and Claim Value. The Claim Name is just a user-friendly string to identify the custom claim. The Claim Value is the attribute in FID

   

4. The mappings page should then display the custom claim with the option to disable or delete it

   

Change Token Expiration Time

Certain situations may require that an OIDC application's token expiration be changed. To do so:

1. Log in as a tenant administrator.
2. Navigate to Administration > Applications > OpenID Connect.
3. Choose Edit next to the application in which the token expiration should be changed.
4. Scroll to the bottom of the page to the Token Expiration Settings section.
5. Modify the values accordingly.
6. Click Save.

CFS supports the PKCE flow, a secure alternative to the implicit flow. PKCE is used mainly for Single-Page Applications (SPAs) in which the client secret cannot be securely stored. These SPAs tend to store information in the browser, and therefore it is recommended to use this flow since it's more secure than the implicit flow.

Since this flow builds off the standard authorization code flow, the steps are very simliar:

1. The user clicks on Login from the OIDC client application
2. The OIDC client application creates a code_verifier
3. The OIDC client application also creates a code_challenge and a code_challenge_method which is either plain or S256
   • If the code_challenge_method is plain, then the code_challenge is just the code_verifier
   • If the code_challenge_method is S256, then the code_challenge is the Base64 URL-encoded SHA256 hashed value of the code_verifier
4. The client sends the code_challenge and code_challenge_method along in the authorization request to CFS
5. CFS stores the code_challenge and responds with an authorization code
6. The client then sends a request containing it's code_verifier and authorization code to CFS' /token endpoint
7. CFS verifies the authorization code and then verifies the code_verifier using the code_challenge and code_challenge_method received in the /authorzie request
   • If the validation is successful, CFS responds with an access token, id_token, and refresh_token
8. The OIDC client the requests, user data to the /userinfo endpoint with the access token issued from step 7
9. CFS verifies the access token, and if correct, responds with the user's information based on thescopesrequested from theaccess token`

When using the PKCE flow, the client_secret is not needed. The code_challenge essentially replaces the client_secret.

A sample authorization request using the PKCE flow is as follows (line breaks included for readability):

GET https://[cfs-server]/cfs/oauth/[tenant-identifier]/authorize?  
client_id=g1hokpYGybxFMw98Hm2GEx  
&redirect_uri=https%3A%2F%2Fwin-cit95mqedh1.luckylemurs.com%2Fsignin-oidc  
&response_type=code  
&scope=openid%20profile%20groups  
&code_challenge=48OXGnJ6mmia6TWwEaVYfm02laegbqABMDGR_20NN98  
&code_challenge_method=S256  
&response_mode=form_post  
&nonce=63762669242...jODg3  
&state=CfDJ...7kV1SZQ8Oj_

Session management in OIDC allows for clients to monitor users' session state in CFS, and act accordingly. It also enables clients to allow users to logout of CFS. OIDC session management can be used to:

• Log users out of all applications they're signed into from an IdP (single-logout)
• End a user's current CFS session (simple logout)

Check Session Management

Clients (Relying Parties (RPs)) can check for users' session status by using CFS' (OpenID Connect Provider's (OP)) /checksession endpoint, which can be found from the OIDC discovery endpoint for the tenant. In order for clients to correctly use the /checksession endpoint, two iframes must be loaded into the client:

• An OP iframe -- an iframe loaded into the RP pointing to the OP's checksession endpoint found in the OIDC discovery document.
  • The RP must assign an id attribute to the iframe so that it can identify it in the OP iframe
  • The RP's postMessage from the iframe sends the following string concatenation as data: client_id + " " + session_state.
• An RP iframe -- an iframe loaded into the RP used to handle the response from the OP's checksession endpoint.
  • This iframe must know the id of the OP iframe and the origin URL of the OP iframe (i.e. https://cfs-server.domain.com) to ensure that requests are sent to and received only from the originating OP (i.e. CFS).

A response from the OP's checksession endpoint is either changed, unchanged, or error.

• If the response is changed, the RP must send a request to the OPs' authorize endpoint with prompt=none with the RP iframe to request a new ID token, sending the old ID token as the id_token_hint.
• If the response is unchanged, the RP need not do anything, as the user's session has not changed.
• If the response is error, the RP must not perform re-authentication to the authorize endpoint.

End Session Mangement

If an OIDC client chooses to allow users to logout of CFS (i.e. simple logout), it can do so from the tenant's endsession endpoint found in the OIDC discovey document. The client must know the ID token for the user, and must pass it in the id_token_hint parameter.

If the ID token is valid, CFS logs the user out and the following page is displayed.

If the ID token is invalid, CFS displays the following page.

If the id_token_hint parameter is not passed, CFS displays the following page.

An example end session request is as follows.

https://cfs-server.domain.com/cfs/oauth/[tenant-identifier]/endsession?id_token_hint=ey8Ujmnr43dC...PZ

Revoking Access to an Application

Once a user authenticates to an OpenID application and gives consent for the application to access their profile attributes, they can log in to the CFS portal and "revoke access" to these applications meaning that the application is no longer allowed to get the user's attributes without consent.

1. Log into the CFS Portal and click Security.
2. Click Edit next to Applications. You will see a list of applications and the scope they are currently using.
3. Click the Revoke button next to the applications you no longer want to be able to access your profile.

PowerShell Commandlets

The Microsoft PowerShell commandlets are available starting CFS version 3.3. 145 of them are available in CFS 3.16.2.

Run the PowerShell prompt and use the following command in order to connect to FID: Connect-CfsService -Address <FID ADDRESS> -Port <SSL PORT> -Root "cn=cfs,cn=config". You are prompted for your FID credentials. After the authentication is successful, you can manage your CFS using the following cmdlets.

If the CFS PowerShell cmdlets are not available after installing CFS, enter the command Import-Module RLI.CFS.Management in order to import the CFS commandlets. Also, make sure you have PowerShell 4.0 (or later) installed.

Schema

Service

Tools

Global Login Page

Bypass Redirection

Packages

Servers

SMTP

Tenants

Themes

Web Gallery

Web Proxy

Tenant

Use command Set-CfsCurrentTenant (Available since CFS 3.4) in order to set the Tenant to use for the current session.

Application

Applications and SmartLinks

Tenant Certificate

Challenge Questions

Emails

Identity Providers

Certificate

Form-Based

RSA SecurID

Yubico

RTC

Trusted

Two-Step

Identity Store

Mappings

Messaging Service

OpenID Connect

Settings

Smart Links

Social Networks