JIT User Provisioning in OAM and SP

This article discusses on how to add user provisioning to OAM/SP which allows the server to create a user record on the fly during Federation SSO, if the user does not have an account yet.

During a Federation SSO operation, OAM/SP validates the incoming SSO response (SAML or OpenID) and attempts to map it to a local LDAP user record based on information contained in the SSO response (typically user attributes):

• If the mapping returns a single user record, the operation is a success and an OAM session is created for that user record

• If the mapping returns several LDAP records, then the operation is a non-recoverable failure:

  • Either the mapping configuration is incorrect
  • Or there are invalid LDAP user records in the directory

• If the mapping does not return any records, this means that

• Either the mapping configuration is incorrect

• Or the configuration is correct, but the user does not have a record in the local directory. In this case, OAM/SP can be set up to automatically create an LDAP user record based on the data contained in the SSO response, and ensure that subsequent Federation SSO mapping operations for that user maps to the same new LDAP user record

OAM/SP validates the SSO response, process the attributes using rules defined in the IdP Attribute Profile for the IdP partner, and if needed invokes the User Provisioning module configured in OAM/SP:

• Either the included User Provisioning module

• Or a custom implementation of a User Provisioning module

After the invocation of the User Provisioning module (default or custom), the server creates a session for the user. Subsequent Federation SSO operations for the same user results in OAM/SP mapping the SSO response to that newly created LDAP record.

Built-in User Provisioning Module

The built-in User Provisioning module allows a user record to be created in the LDAP directory when mapping fails by:

• Using the Identity Store specified in the IdP partner entry, or the default OAM Identity Store if none is specified

• Using the User Base DN specified in the IdP partner entry, or the User Base DN for the Identity Store that is used, if none is specified

• Creating a user record with a userID based on an attribute contained in the SAML/OpenID SSO Response:

• Either the User Provisioning module configuration indicates which attribute to use as the userID (for example foo)

• The module attempts to locate that attribute in the list of attributes from the SSO response after those attributes were processed by the IdP Attribute Profile (for example the module looks for the foo attribute in the list of processed attribute from the SSO response)

• If the attribute is not in the list of attributes from the SSO response, the module evaluates the mapping rule specified in the IdP Partner entry: if the mapping rule uses the userID attribute, then it uses the mapped data as the userID (for example, if the SAML Assertion was mapped via NameID to an LDAP user record using the foo LDAP attribute, then the module uses the NameID value as the userID)

• Or the User Provisioning module configuration does not indicate which attribute to use as the userID or if the userID attribute could not be determined following the above flow, the module looks at the Identity Store configuration to determine the userID attribute (for example uid) and it follows the process listed above

• The module attempts to locate that attribute in the list of attributes from the SSO response after those attributes were processed by the IdP Attribute Profile (for example the module looks for the uid attribute in the list of processed attribute from the SSO response)

• If the attribute is not in the list of attributes from the SSO response, the module evaluates the mapping rule specified in the IdP Partner entry. If the mapping rule uses the userID attribute, then it uses the mapped data as the userID (for example, if the SAML Assertion was mapped via NameID to an LDAP user record using the uid LDAP attribute, then the module uses the NameID value as the userID)

• If the userID attribute could still not be determined (because uid is not in the list of attributes sent by the IdP for example), the module attempts to use the NameID value as the userID

• If present it uses it

• Otherwise an error is thrown since the User Provisioning module cannot select a userID value.

Important Note: The above algorithm is somewhat complex, but it allows an administrator

• To test user provisioning in a POC without having to perform multiple configuration steps as well as to configure the user provisioning module to the administrator’s needs.

• Once the user record has been created, the User Provisioning module sets attributes on the user record based on:

• The list of attributes that should be set: This is indicated by the module’s configuration set by the administrator, which dictates the list of attributes from the SSO response to set

• The attributes listed in the mapping rule: The attributes listed in the mapping rule of the IdP Partner entry is automatically set in the LDAP user record, to ensure that the mapping functions the next time the user with an identical SSO response performs Federation SSO with OAM/SP.

Enabling User Provisioning in OAM/SP

Perform the following steps to enable/disable User Provisioning in OAM/SP:

1. Enter the WLST environment by executing: $IAM_ORACLE_HOME/common/bin/wlst.sh

2. Connect to the WLS Admin server: connect()

3. Navigate to the Domain Runtime branch: domainRuntime()

4. Update the userprovisioningenabled property to:

• Enable User Provisioning in OAM/SP: putBooleanProperty("/fedserverconNg /userprovisioningenabled", "true")

• Disable User Provisioning in OAM/SP: putBooleanProperty("/fedserverconNg /userprovisioningenabled", "false")

5. Exit the WLST environment: exit()

Testing Setup

Use the same SAML 2.0 Federation setup that was previously configured, where:

• OAM acts as a Service Provider

• The IdP (AcmeIdP) sends a SAML Assertion with

  • NameID set to userID

  • Attributes sent:

    • email set to user’s email address

    • fname set to user’s first name

    • surname set to user’s last name

    • title set to user’s last job title

• OAM/SP configured with an IdP Attribute Profile to

  • Map fname to givenname

  • Map surname to sn

  • Map email to mail

  • User alice is used at the IdP, while no user account for alice exists at OAM/SP:

    • userID: alice
    • email: [e-mail]
    • first name: Alice
    • last name: Appleton
    • title: manager

During a SAML 2.0 Federation SSO with the remote IdP partner, the XML SAML Response with the Assertion sent back by the IdP would be:

<samlp:Response ..>
    <saml:Issuer ...>http://acme.com/idp</saml:Issuer>
    <samlp:Status>
        <samlp:StatusCode
Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
    </samlp:Status>
    <saml:Assertion ...>
        <saml:Issuer ...>http://acme.com</saml:Issuer>
        <dsig:Signature ...>
        ...
        </dsig:Signature>
        <saml:Subject>
<saml:NameID ...>alice</saml:NameID>
            ...
        </saml:Subject>         <saml:Conditions ...>
         ...
        </saml:Conditions>         <saml:AuthnStatement ...>
        ...
        </saml:AuthnStatement>
        <saml:Attributestatement ...>
            <saml:Attribute Name="email" ...>
                <saml:AttributeValue
...>[e-mail]</saml:AttributeValue>
            </saml:Attribute>
            <saml:Attribute Name="title" ...>
                <saml:AttributeValue
...>manager</saml:AttributeValue>
            </saml:Attribute>
            <saml:Attribute Name="surname" ...>
                <saml:AttributeValue
...>Appleton</saml:AttributeValue>
            </saml:Attribute>
            <saml:Attribute Name="fname" ...>
                <saml:AttributeValue
...>Alice</saml:AttributeValue>
            </saml:Attribute>
        </saml:Attributestatement>
    </saml:Assertion>
</samlp:Response>

The result of the processing of the SAML 2.0 Assertion by OAM/SP shows the transformed attributes as well as the NameID

Description of the illustration Operation_Result.jpg

Test Cases

The test cases showcases different configurations for the User Provisioning module, with the user alice not existing in OAM/SP before each test:

Use Case #1:

• No User Provisioning module configuration

• Mapping rule is done via NameID to LDAP uid attribute

Use Case #2:

• No User Provisioning module configuration

• Mapping rule is done via SAML Attribute mail to LDAP mail attribute

Use Case #3:

• Mapping rule is done via NameID to LDAP uid attribute

• User Provisioning module configured to set givenname, sn and mail attributes

Use Case #4:

• Mapping rule is done via SAML Attribute mail to LDAP mail attribute

• User Provisioning module configured to use givenname as the userID

Use Case #5:

• Mapping rule is done via SAML Attribute mail to LDAP mail attribute

• User Provisioning module configured to Use NameID as the userID

• Set givenname and sn attributes

After each Federation SSO operation, print out the LDAP user record of the user created and subsequently deletes that record before the next test.

Important note: The IdP Attribute Profile must map the incoming SAML Attribute names to the attribute names that is used in the LDAP directory. That’s why in our test IdP Attribute Profile, fname is mapped to givenname. The built-in User Provisioning plugin takes the attribute names from the list of processed attributes and add them as is to the LDAP user record (if configured to do so): there is no additional attribute name mapping.

Use Case #1

In this use case, the setup is such that:

• No User Provisioning module configuration

• Mapping rule is done via NameID to LDAP uid attribute

After Federation SSO, the user record for alice was created:

dn: uid=alice,ou=users,dc=us,dc=oracle,dc=com
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
objectClass: top
uid: alice
cn: alice
sn: alice

The LDAP user record has the following characteristics:

• UserID:

  • There was no User Provisioning module configuration

  • The User Provisioning module checked if the User Identity Store UserID (uid in the test) was an attribute sent by the IdP: this was not the case

  • The User Provisioning module used the NameID as the userID (which is stored in the LDAP uid attribute): uid was set to alice

• Extra attributes:

  • The User Provisioning module set the attribute(s) that was used in the mapping rule: NameID was mapped to uid. This attribute was already set (as the userID).

  • cn and sn are mandatory attributes as per the LDAP schema used in this test, and if not explicitly specified, userID is used to populate those attributes

Use Case #2

In this use case, the setup is such that:

• No User Provisioning module configuration

• Mapping rule is done via SAML Attribute mail to LDAP mail attribute

After Federation SSO, the user record for alice was created:

dn: uid=alice,ou=users,dc=us,dc=oracle,dc=com
mail: [e-mail]
objectClass: person
objectClass: inetOrgPerson
objectClass: organizationalPerson
objectClass: top
uid: alice
cn: alice
sn: alice

The LDAP user record has the following characteristics:

• UserID:

  • There was no User Provisioning module configuration

  • The User Provisioning module checked if the User Identity Store UserID (uid in the test) was an attribute sent by the IdP: this was not the case

  • The User Provisioning module used the NameID as the userID (which is stored in the LDAP uid attribute): uid was set to alice

• Extra attributes:

  • The User Provisioning module set the attribute(s) that was used in the mapping rule: the email attribute in the SAML assertion was mapped to mail. The mail attribute was set to [e-mail]

  • cn and sn are mandatory attributes as per the LDAP schema used in this test, and if not explicitly specified, userID is used to populate those attributes

Use Case #3

In this use case, the setup is such that:

• Mapping rule is done via NameID to LDAP uid attribute

• User Provisioning module configured to set givenname, sn and mail attributes.

To do so, perform the following steps:

1. Go to the OAM Administration Console: http(s)://oam-admin-host:oam-adminport/oamconsole

2. Navigate to Access Manager, Plugins

3. Select the FedUserProvisioningPlugin

4. In the KEY_USER_RECORD_ATTRIBUTE_LIST field, enter givenname, sn and mail as a comma separated list without spaces: givenname,sn,mail

5. Click Save

Description of the illustration Plug_ins_Screen.jpg

After Federation SSO, the user record for alice is created:

dn: uid=alice,ou=users,dc=us,dc=oracle,dc=com
mail: [e-mail]
givenName: Alice
objectClass: person
objectClass: inetOrgPerson
objectClass: organizationalPerson
objectClass: top
uid: alice
cn: alice
sn: alice
sn: Appleton

The LDAP user record has the following characteristics:

• UserID:

  • There was no User Provisioning module configuration for userID

  • The User Provisioning module checked if the User Identity Store UserID (uid in the test) was an attribute sent by the IdP: this was not the case

  • The User Provisioning module used the NameID as the userID (which is stored in the LDAP uid attribute): uid was set to alice

• Extra attributes:

  • The User Provisioning module set the attribute(s) that was used in the mapping rule: NameID was mapped to uid. This attribute was already set (as the userID).

  • The User Provisioning module retrieved the givenname, sn and mail attributes from the list of processed attributes and set those on the LDAP user record.

  • cn is a mandatory attribute as per the LDAP schema used in this test, and if not explicitly specified, userID is used to populate that attribute

Use Case #4

In this use case, the setup is such that:

• Mapping rule is done via SAML Attribute mail to LDAP mail attribute

• User Provisioning module configured to use givenname as the userID

To do so, perform the following steps:

1. Go to the OAM Administration Console: http(s)://oam-admin-host:oam-adminport/oamconsole

2. Navigate to Access Manager, Plugins

3. Select the FedUserProvisioningPlugin

4. Set the KEY_USER_RECORD_ATTRIBUTE_LIST field to blank value

5. Set the KEY_USERID_ATTRIBUTE_NAME field to givenname

6. Click Save

Description of the illustration Access_mngt.jpg

After Federation SSO, the user record for alice is created:

dn: uid=Alice,ou=users,dc=us,dc=oracle,dc=com
mail: [e-mail]
objectClass: person
objectClass: inetOrgPerson
objectClass: organizationalPerson
objectClass: top
uid: Alice
cn: Alice
sn: Alice

The LDAP user record has the following characteristics:

• UserID:

  • The User Provisioning module was configured to use givenname as the userID

• Extra attributes:

  • The User Provisioning module set the attribute(s) that was used in the mapping rule: the email attribute in the SAML assertion was mapped to mail. The mail attribute was set to [e-mail].

  • cn and sn are mandatory attributes as per the LDAP schema used in this test, and if not explicitly specified, userID is used to populate those attributes

Use Case #5

In this use case, the setup is such that:

• Mapping rule is done via SAML Attribute mail to LDAP mail attribute

• User Provisioning module configured to

  • Use NameID as the userID

  • Set givenname and sn attributes

To do so, perform the following steps:

1. Go to the OAM Administration Console: http(s)://oam-admin-host:oam-adminport/oamconsole

2. Navigate to Access Manager, Plugins

3. Select the FedUserProvisioningPlugin

4. Set the KEY_USER_RECORD_ATTRIBUTE_LIST field to (comma separated list without spaces): givenname,sn

5. Set the KEY_USERID_ATTRIBUTE_NAME field to fed.nameidvalue, which is the name of the attribute for the NameID value

6. Click Save

Description of the illustration Access_mngt_nameID_Value.jpg

After Federation SSO, the user record for alice is created:

dn: uid=alice,ou=users,dc=us,dc=oracle,dc=com
mail: [e-mail]
givenName: Alice
objectClass: person
objectClass: inetOrgPerson
objectClass: organizationalPerson
objectClass: top
uid: alice
cn: alice
sn: alice
sn: Appleton

The LDAP user record has the following characteristics:

• UserID:

  • The User Provisioning module was configured to use the NameID value (fed.nameidvalue) as the userID

• Extra attributes:

  • The User Provisioning module set the attribute(s) that was used in the mapping rule: the email attribute in the SAML assertion was mapped to mail. The mail attribute was set to [e-mail].

  • The User Provisioning module retrieved the givenname and sn attributes from the list of processed attributes and set those on the LDAP user record.

  • cn is a mandatory attribute as per the LDAP schema used in this test, and if not explicitly specified, userID is used to populate that attribute

More Learning Resources

Explore other labs on docs.oracle.com/learn or access more free learning content on the Oracle Learning YouTube channel. Additionally, visit education.oracle.com/learning-explorer to become an Oracle Learning Explorer.

For product documentation, visit Oracle Help Center.

---

Title and Copyright Information

JIT User Provisioning in OAM and SP

F61369-01

September 2022

Copyright © 2022, Oracle and/or its affiliates.