JIT User Provisioning in OIF / SP

In this article, I will discuss on how to add user provisioning to OIF/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, OIF/SP will validate the incoming SSO response (SAML or OpenID) and will attempt 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, OIF/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 will map to the same new LDAP user record

OIF/SP will validate the SSO response, process the attributes using rules defined in the IdP Attribute Profile for the IdP partner, and if needed will invoke the User Provisioning module configured in OIF/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 will create a session for the user. Subsequent Federation SSO operations for the same user will result in OIF/SP mapping the SSO response to that newly created LDAP record.

Enjoy the reading!

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 will attempt 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 will look 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 will evaluate the mapping rule specified in the IdP Partner entry: if the mapping rule uses the userID attribute, then it will use 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 will use 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 will look at the Identity Store configuration to determine the userID attribute (for example uid) and it will follow the process listed above:
      • The module will attempt 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 will look 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 will evaluate the mapping rule specified in the IdP Partner entry: if the mapping rule uses the userID attribute, then it will use 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 will use 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 will attempt to use the NameID value as the userID
      • If present it will use it
      • Otherwise an error will be 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 moduble to the administrator’s needs.
  • Once the user record has been created, the User Provisioning module will set 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 will be automatically set in the LDAP user record, to ensure that the mapping will function the next time the user with an identical SSO response performs Federation SSO with OIF/SP.

Enabling User Provisioning in OIF/SP


To enable/disable User Provisioning in OIF/SP, execute the following steps:

  • Enter the WLST environment by executing:
    $IAM_ORACLE_HOME/common/bin/wlst.sh
  • Connect to the WLS Admin server:
    connect()
  • Navigate to the Domain Runtime branch:
    domainRuntime()
  • Update the userprovisioningenabled property to:
    • Enable User Provisioning in OIF/SP:
      putBooleanProperty("/fedserverconfig/userprovisioningenabled", "true")
    • Disable User Provisioning in OIF/SP:
      putBooleanProperty("/fedserverconfig/userprovisioningenabled", "false")
  • Exit the WLST environment:
    exit()

Testing Setup


I will use the same SAML 2.0 Federation setup that was configured in the previous articles, where:

  • OIF acts as a Service Provider
  • The IdP (AcmeIdP) will send 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
  • OIF/SP configured with an IdP Attribute Profile to
    • Map fname to givenname
    • Map surname to sn
    • Map email to mail
  • User alice will be used at the IdP, while no user account for alice exists at OIF/SP:
    • userID: alice
    • email: alice@oracle.com
    • 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 ...>alice@oracle.com</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 OIF/SP will show the transformed attributes as well as the NameID

Test Cases


I will showcase different configurations for the User Provisioning module, with the user alice not existing in OIF/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, I will print out the LDAP user record of the user created. I will subsequently delete that record before the next test.

Important note: the IdP Attribute Profile must map the incoming SAML Attribute names to the attribute names that will be 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 will take 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 the test will be 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: alice@oracle.com
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 the test will be 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 alice@oracle.com.
    • 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:
  • Go to the OAM Administration Console: http(s)://oam-admin-host:oam-admin-port/oamconsole
  • Navigate to Access Manager -> Plugins
  • Select the FedUserProvisioningPlugin
  • In the KEY_USER_RECORD_ATTRIBUTE_LIST field, enter givenname, sn and mail as a comma separated list without spaces: givenname,sn,mail
  • Save

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

dn: uid=alice,ou=users,dc=us,dc=oracle,dc=com
mail: alice@oracle.com
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 the test will be 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:
    • Go to the OAM Administration Console: http(s)://oam-admin-host:oam-admin-port/oamconsole
    • Navigate to Access Manager -> Plugins
    • Select the FedUserProvisioningPlugin
    • Set the KEY_USER_RECORD_ATTRIBUTE_LIST field to blank value
    • Set the KEY_USERID_ATTRIBUTE_NAME field to givenname
    • Save

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

dn: uid=Alice,ou=users,dc=us,dc=oracle,dc=com
mail: alice@oracle.com
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 alice@oracle.com.
    • 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:
    • Go to the OAM Administration Console: http(s)://oam-admin-host:oam-admin-port/oamconsole
    • Navigate to Access Manager -> Plugins
    • Select the FedUserProvisioningPlugin
    • Set the KEY_USER_RECORD_ATTRIBUTE_LIST field to (comma separated list without spaces): givenname,sn
    • Set the KEY_USERID_ATTRIBUTE_NAME field to fed.nameidvalue, which is the name of the attribute for the NameID value
    • Save

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

dn: uid=alice,ou=users,dc=us,dc=oracle,dc=com
mail: alice@oracle.com
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 alice@oracle.com.
    • 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


In my next article, I will show how a custom User Provisioning module can be implemented and used by OIF/SP to create user records on the fly.
Cheers,
Damien Carru

Comments:

Post a Comment:
  • HTML Syntax: NOT allowed
About

Damien Carru is a member of the Oracle Identity Management organization, focusing on Federation and SSO. This blog will cover Federation use cases involving Oracle Access Manager, Oracle Identity Federation and Oracle Security Token Service

Search

Categories
Archives
« April 2015
SunMonTueWedThuFriSat
   
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
17
18
19
20
21
22
23
24
25
26
27
28
29
30
  
       
Today