G Identity Provider Integration
Here are the steps you need to follow to integrate various third-party identity providers with OMCe.
Use Case: Configuring OKTA to Obtain a SAML Token
Use Case: Configuring AD FS to Obtain a SAML Token
Configuring Active Directory Federation Services (AD FS) to obtain a SAML token involves providing similar information as you would for configuring another identity provider to obtain the token. You’ll configure an audience, provide a redirect URL to obtain the token, and configure some rules.
In addition to having access to the AD FS server, you’ll need the following items:
-
A defined set of users and groups.
-
A Certificate Authority (CA) root certificate and a Signing Certificate from a valid certificate authority. You’ll import these certificates into your AD FS instance.
These are the token certificates and corresponding private key that are imported into AD FS so that it can generate and sign SAML tokens. These certificates must also be added to the Token Certificates panel of the CSF Keys and Certificate dialog in OMCe so that OMCe can validate the token. These are the token certificates that will be associated with the token issuer in OMCe.
For testing purposes, you can create a root certificate and a self-signing certificate as shown in the following examples but don’t use them in a production environment.
Here’s an example of how to create a root certificate:
$ openssl req -x509 -nodes -days 3650 -subj "/C=US/ST=CA/L=Local/O=SampleCA/OU=Self-Signed/CN=ca.test.local" -newkey rsa:2048 -keyout testCARootPrivateKey.key -out testCARootCertificate.crt
Here’s an example of how to create a new key pair and the corresponding certificate:
$ openssl req -nodes -days 3650 -subj "/C=US/ST=CA/L=Local/O=SampleCA/OU=Self-Signed/CN=sts-signing.test.local" -newkey rsa:2048 -keyout testSigningPrivateKey.key -out testSigningCertificate.csr
$ openssl x509 -req -days 3650 -in testSigningCertificate.csr -CA ../ca/testCARootCertificate.crt -CAkey ../ca/testCARootPrivateKey.key -CAcreateserial -out testSigningCertificate.crt
$ openssl pkcs12 -export -out testSigningCertificate.pfx -inkey testSigningPrivateKey.key -in testSigningCertificate.crt
Creating Users and Groups in AD FS
You need to create users and assign them to groups in AD FS. In OMCe, these user groups are mapped to existing OMCe roles. This assumes that you have the AD FS server installed.
Start AD and add users:
-
Select Tools > Active Directory Users and Computers.
-
Open the
Active Directory and Users and Computers
folder.This is the directory where you’ll add users and groups.
-
Right-click the
Users
folder and select New > User. -
In the New Object - User dialog, provide a first and last name for each user you add and the user logon name. The logon name must match the user email address for that user in OMCe.
For example, if the user is John Smith, and his address is
jsmith@local.domain
, the address must match the email address for user John Smith in OMCe. -
Click Next and then OK to add the user.
Repeat these steps for each user you want to add.
To add a group and assign a user to it:
-
Right-click the Users folder in the
Active Directory and Users and Computers
directory and select New > Group. -
In the New Object - Group dialog, enter a name for the group.
-
Leave the default settings of Global and Security, for Group Scope and Group Type and click OK.
-
Right-click on the user name in the
Active Directory and Users and Computers
directory and select Add to a group.... -
In the Select Group dialog, click Advanced.
-
In the advanced version of the Select Groups dialog, click Find Now.
-
Locate the group name from the Search results list, select it, and click OK.
-
Click OK in the Select Group dialog to complete the group assignment.
To verify that you’ve added the user to the correct group:
-
Click on the group name in the
Active Directory and Users and Computers
directory to open the group’s properties dialog. -
In the properties dialog, click Members and look to see if the user you added is listed.
A group should have a corresponding role in OMCe. The user assigned to the group would then be assigned to the corresponding OMCe role.
Configuring the SAML App in AD FS
After you’ve added your users and groups and have a valid root certificate and signing certificate, you can configure the SAML token. You’ll begin by adding and configuring a relying party trust. The relying party defines the way in which AD FS recognizes the relying party application and issues claims to it.
-
From the Server Manager, select Tools > AD FS Management.
-
In the AD FS window, select Action > Add Relying Party Trust....
-
Click Start in the Add Relying Trust wizard.
-
On the Select Data Source panel, select Enter data about the relying party trust manually option.
-
Click Next to go to the Specify Display Name panel.
-
Enter the name of your SAML app in the Display Name field.
This app name will be listed in the
Trust Relationships > Relying Party Trust
directory after you add it. -
Click Next to go to the Choose Profile panel.
-
Select AD FS profile (the default value).
This is the profile type that supports the SAML 2.0 protocol.
-
Click Next and Next again to go to the Configure URL panel.
You can upload the signing certificate on the Configure Certificate panel now or upload it later. You don’t need to upload an encryption certificate unless you want the SAML assertion encrypted as well as signed. Having an encrypted SAML assertion can be useful in cases where sensitive data is added to the SAML assertion claims.
-
Select Enable support for the SAML 2.0 Web SSO protocol and enter the redirect URL in the Relying party SAML 2.0 SSO service URL field.
The redirect URL is the address where you want the request to post back to so you can intercept the token.
-
Click Next to go to the Configure Identifiers panel.
-
Enter the SSO token endpoint in the Relying party trust identifier field and click Add.
You construct this endpoint by appending
/mobile/platform/sso/exchange-token
to your instance’s base URL. You can determine the base URL by opening any mobile backend in OMCe, clicking its Settings tab, and looking in the Environment URLs section. For example:https://hostname:443/mobile/platform/sso/exchange-token
This is how you specify the audience for the SAML assertion.
-
Click Next to go to the Configure Multi-factor Authentication Now panel.
Use the default setting, I do not want to configure multi-factor authentication settings for this relying party trust.
-
Click Next to go to the Choose Issuance Authorization Rules panel.
Use the default setting, Permit all users to access this relying party.
-
Click Next to go to the Ready to Add Trust panel, click Next again.
-
Click Finish.
Leave the default setting, Open the Edit Claim Rules dialog for this relying party trust to continue configuring your SAML app.
-
Click Close to exit the wizard.
The Edit Claim Rules dialog opens when you exit the wizard.
Configuring Claim Rules in AD FS
The next step to configure your SAML app is setting the claim rules. The claim rule specifies how the values for LDAP attributes are mapped to the outgoing claim type. You’ll use the Add Transform Claim Rule wizard available from the Edit Claim Rules dialog to add AD claims and transform NameID transform rule which specify the claims that are sent to the relying party.
-
Open the
Relying Party Trust
folder under theTrust Relationships
directory and right-click your app name. Then select Edit Claim Rules.If you’re continuing on from the previous section, the Edit Claim Rules dialog opens automatically when you exit the Add Relying Trust wizard.
-
Make sure the Issuance Transform Rules tab is open and click Add Rule to open the Add Transform Claim Rule wizard.
-
In the Choose Rule Type tab, select the Send LDAP Attributes as Claims template from the drop-down list.
-
Click Next to go to the Configure Claim Rule tab.
-
Enter a claim rule name. For example,
AD Claims
. -
Select Active Directory as the Attribute store.
In the next set of steps, you’ll map the LDAP attributes to the outgoing claim types:LDAP Attributes Outgoing Claim Type E-Mail Addresses
E-Mail Address
Token-Groups-Unqualified Name
Group
User-Principal-Name
Common Name
-
Open the LDAP Attributes list and select
E-Mail Addresses
. -
Open the Outgoing Claim Type list and select
E-Mail Address
. -
Repeat steps 7 and 8 to map
Token-Groups-Unqualified Name
toGroup
and to mapUser-Principal-Name
toCommon Name
. -
Click Finish.
Configuring Transform Rules in AD FS
You set transform rules to map incoming claim types to outgoing claim types and specify the action that determines what output should occur based on the values from the incoming claim.
-
Open the Edit Claim Rules dialog and open the Issuance Transform Rules tab.
-
Click Add Rule to open the Add Transform Claim Rule wizard.
-
In the Choose Rule Type tab, select Transform an Incoming Claim.
-
Click Next to go to the Configure Claim Rule tab.
-
Perform the following actions on this tab:
-
Enter
Transform NameID
for the transform claim rule. -
Select EMAIL ADDRESS for the incoming claim type.
-
Select Name ID for the outgoing claim type.
-
Leave as unspecified the ingoing and outgoing nameID formats.
-
Select the Pass through all claim values option.
-
-
Click Finish.
-
Click Apply and OK in the Edit Claim Rules dialog.
Specifying the Signature Verification Certificate in AD FS
You must specify the signature verification certificates for requests from the relying party trust.
-
Open the
Relying Party Trusts
folder, right-click your app name, and select Properties. -
In the properties dialog for your app, select Signature and click Add.
-
In the Select a Request Signature Verification Certificate dialog, navigate to the directory where you stored (or created) the signing certificate and select the certificate.
-
Click Open.
-
(Optional) Click the Endpoints tab in the app properties dialog and review the SAML assertion endpoints.
Click the endpoint URL to view its details in the Edit Endpoint dialog. The endpoint type should beSAML Assertion Consume
. Set the Binding field for the type of SAML response to receive:-
If the client expects a POST, set Binding to
POST
. -
If the client expects to receive the SAML Response as a
GET
parameter, set Binding toRedirect
.Note:
There can be issues using a redirect in the case of long assertions because some browsers have limits to the length of the URL.
-