1. Developing Applications with Oracle Mobile Cloud Enterprise
  2. Identity Provider Integration

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

Here are the required fields that you must fill-in if you’re configuring a SAML 2.0 app from OKTA.
Assuming that you have a user role with administrator privileges in OKTA:
  1. Log in to OKTA.
  2. Click Admin.
  3. Go to the Directory tab and specify the users to have access privileges to the application:

    • Select People to specify individual users.

    • Select Group to specify a group of users.

      By setting a group, you can later map a group of individuals to specific OMCe roles by setting Role Attribute rules in the Keys and Certificates dialog.

    • Select Directory Integration, then Add Active Directory to include all the users in the directory server or, alternatively, select LDAP to include all the users in an LDAP directory server

  4. Go to the Applications tab and click Add Application to create a new SAML 2.0 application.
  5. On the General Settings page, configure the SAML application.
    You’ll see several fields to fill in. For the token to be viable with OMCe, you must fill-in the following fields:

    • Single Sign-On URL. This is the redirect URL where the response from the third-party IdP is sent. For example:

      https://hostname:####/saml

    • Audience URI. This is the intended audience of the SAML assertion and ensures that you can exchange an externally-issued SAML token that you need to call OMCe APIs. Set this value to the OMCe SSO token exchange endpoint.

      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

    • Group Statement. This is where you can add additional group attributes to the token. In this field, you can filter which groups to add. There are different types of filtering options that you can choose from. For instance, if you used a naming convention for your group names, you can set an option (Regex or Start with) to filter groups that begin with a specific prefix.

      For example, say you defined several group of users, two groups for FixItFast employees, FIF-group1 and FIF-group2, and a group for RepairItFast employees, RIF-group1. If you enter FIF* as a value, only the users in the FixItFast group are added to the token.

  6. Once you’ve configured the app, go to the Single Sign-On page.
    This is where you’ll get the token issuer name that you’ll enter into the Token Issuer panel of the token issuer in Settings > Credentials in OMCe. See Adding a Token Issuer in Administering Oracle Mobile Cloud, Enterprise.
    You’ll also want to get token certificate contents from this page and paste them in the Certificate panel for the certificate in Settings > Credentials. See Configuring a Web Service or Token Certificate in the same guide.

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:

  1. Select Tools > Active Directory Users and Computers.

  2. Open the Active Directory and Users and Computers folder.

    This is the directory where you’ll add users and groups.

  3. Right-click the Users folder and select New > User.

  4. 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.

  5. 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:

  1. Right-click the Users folder in the Active Directory and Users and Computers directory and select New > Group.

  2. In the New Object - Group dialog, enter a name for the group.

  3. Leave the default settings of Global and Security, for Group Scope and Group Type and click OK.

  4. Right-click on the user name in the Active Directory and Users and Computers directory and select Add to a group....

  5. In the Select Group dialog, click Advanced.

  6. In the advanced version of the Select Groups dialog, click Find Now.

  7. Locate the group name from the Search results list, select it, and click OK.

  8. Click OK in the Select Group dialog to complete the group assignment.

To verify that you’ve added the user to the correct group:

  1. Click on the group name in the Active Directory and Users and Computers directory to open the group’s properties dialog.

  2. 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.

  1. From the Server Manager, select Tools > AD FS Management.

  2. In the AD FS window, select Action > Add Relying Party Trust....

  3. Click Start in the Add Relying Trust wizard.

  4. On the Select Data Source panel, select Enter data about the relying party trust manually option.

  5. Click Next to go to the Specify Display Name panel.

  6. 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.

  7. Click Next to go to the Choose Profile panel.

  8. Select AD FS profile (the default value).

    This is the profile type that supports the SAML 2.0 protocol.

  9. 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.

  10. 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.

  11. Click Next to go to the Configure Identifiers panel.

  12. 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.

  13. 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.

  14. Click Next to go to the Choose Issuance Authorization Rules panel.

    Use the default setting, Permit all users to access this relying party.

  15. Click Next to go to the Ready to Add Trust panel, click Next again.

  16. Click Finish.

    Leave the default setting, Open the Edit Claim Rules dialog for this relying party trust to continue configuring your SAML app.

  17. 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.

  1. Open the Relying Party Trust folder under the Trust 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.

  2. Make sure the Issuance Transform Rules tab is open and click Add Rule to open the Add Transform Claim Rule wizard.

  3. In the Choose Rule Type tab, select the Send LDAP Attributes as Claims template from the drop-down list.

  4. Click Next to go to the Configure Claim Rule tab.

  5. Enter a claim rule name. For example, AD Claims.

  6. 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

  7. Open the LDAP Attributes list and select E-Mail Addresses.

  8. Open the Outgoing Claim Type list and select E-Mail Address.

  9. Repeat steps 7 and 8 to map Token-Groups-Unqualified Name to Group and to map User-Principal-Name to Common Name.

  10. 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.

  1. Open the Edit Claim Rules dialog and open the Issuance Transform Rules tab.

  2. Click Add Rule to open the Add Transform Claim Rule wizard.

  3. In the Choose Rule Type tab, select Transform an Incoming Claim.

  4. Click Next to go to the Configure Claim Rule tab.

  5. 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.

  6. Click Finish.

  7. 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.

  1. Open the Relying Party Trusts folder, right-click your app name, and select Properties.

  2. In the properties dialog for your app, select Signature and click Add.

  3. 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.

  4. Click Open.

  5. (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 be SAML 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 to Redirect.

      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.