SAML Profile Data
Overview
This article outlines how user profile data is sent from iMIS, via SAML attributes, to third-party resources / sites.
Authoring Your Profile IQA
Here are some tips when authoring your Profile IQA.
Your base object should be CsNameUser. Then, you can join CsContact with the following relationship: When CsNameUser.Id = CsContact.iMIS Id
The profile IQA must filter on the iMIS Username (NOT the iMIS ID!). It should have only one visible prompt, marked required, filtering on CsNameUser.User Id.
Other non-prompt filters are OK to add (using "AND" logic).
You may display any columns you wish.
Sorting is not necessary, as this IQA should always only return one result.
Always enter column aliases into the Alias field. (The standard iMIS column names do not translate correctly into SSO field names.)
The profile IQA must always return exactly one result, when queried using an iMIS username.
You cannot use the "Limit query results" feature to limit the results. The iMIS REST API does not respect this setting. Your IQA must return one result without enabling this option.
For dealing with non-numeric fields, you can add a custom SQL expression into the IQA to format the results as needed. Don't forget to include the alias! For example:
Expression Alias FORMAT([vBoCsContact].[BirthDate], 'd', 'en-us')
birthdate
Will format the birthdate in U.S. format, ex: 11/26/1985
Sample IQA
CSI provides a sample IQA for you to download as a starting point. It contains a number of out-of-the-box iMIS fields as well as the correct OpenID field names (see below).
Click here to download the sample IQA:
NameID Formats
The SAML NameID is effectively the username, except with SAML there are many different ways to represent a person / subject besides just their username.
Be sure to select a NameID format that your SP expects. This information is usually found in their documentation, as well as their metadata document.
The following NameID formats are supported by the Cloud SSO app:
Name | SAML URN | Example Data | Description |
---|---|---|---|
Unspecified (Username) |
| BSMITH88 | The iMIS username is sent as the NameID. |
Unspecified (iMIS ID) |
| 1003817 | The iMIS ID is sent as the NameID. |
| bsmith@example.org | The iMIS primary e-mail address is sent as the NameID. | |
Persistent |
| 6c555a4f-a7e2-4f4c-b82c-d3e56927928a | The iMIS Net Contact Key is sent. This is a GUID which uniquely identifies an individual in iMIS, but has no meaning to a third party. |
Transient |
| RrILhAy45XcEYzhCt9Hn | A pseudo-random 20-character alphanumeric identifier is generated for each request and sent as the identifier. |
Attributes
SAML Attributes are key-value pairs of data related to the user signing in.
There are two options that drive the SAML Attributes: Profile IQA Query Path and Role IQA Query Path.
SAML attributes are completely optional. Therefore, it is not required to enter any IQA paths in order to perform SAML authentication.
Regardless of the profile settings that are set, the NameID is always sent in the desired format.
Profile IQA Query Path
If this option is specified, the IQA is run and the username of the user signing in is passed as the only parameter to the IQA.
The IQA is expected to return ONE result row and can contain as many columns of information as necessary.
Column names are SAML attribute names, and row values are SAML attribute values.
Role IQA Query Path
If this option is selected, the IQA is run and the username of the user signing in is passed as the only parameter to the IQA.
The IQA is expected to return ONE column of data and can contain as many rows of information as necessary. The data is expected to be string or string-like (N/VARCHAR). If multiple columns are returned, only the first column is used.
Each row in the results is treated as a value. Depending on the Role Assertion Format setting, the values are either passed as an array, or as a comma-separated string.
SAML URN Attribute Names (Optional)
SAML / LDAP Attribute name URNs are supported. You will need to specify these URNs as the column names in the IQA to pass them to the SP.
SAML URNs are auto-detected in column names. If a column name begins with urn:oid:... then it is sent with the URI attribute name format (instead of basic format).
Regardless of the data type of the column returned from the IQA, the Cloud SSO always transmits the attribute in string format.
If you find that some numeric, date, bit, or other data types are not being formatted correctly when sent in the SAML attribute, try wrapping the column in a CAST()
or CONVERT()
statement to format the data as needed within the IQA or SQL.
LDAP OID Common Attributes
The following table lists some common LDAP OIDs that can be used if the connecting SP requires them.
Display Name | OID | SAML Attribute Name |
---|---|---|
Username / UID / User Principal | 0.9.2342.19200300.100.1.1 (Username) | urn:oid:0.9.2342.19200300.100.1.1 |
Name / Common Name / Display Name | 2.5.4.3 | urn:oid:2.5.4.3 |
First Name / Given Name | 2.5.4.42 | urn:oid:2.5.4.42 |
Last Name / Surname / Family Name | 2.5.4.4 | urn:oid:2.5.4.4 |
0.9.2342.19200300.100.1.3 | urn:oid:0.9.2342.19200300.100.1.3 | |
Telephone Number | 2.5.4.20 | urn:oid:2.5.4.20 |
Company / Organization Name | 2.5.4.10 | urn:oid:2.5.4.10 |
Title | 2.5.4.12 | urn:oid:2.5.4.12 |
Department | 2.5.4.11 | urn:oid:2.5.4.11 |
Address | 2.5.4.9 | urn:oid:2.5.4.9 |
Address 2 | 2.5.4.51 | urn:oid:2.5.4.51 |
City / Locality | 2.5.4.7 | urn:oid:2.5.4.7 |
State / Province | 2.5.4.8 | urn:oid:2.5.4.8 |
Zip / Postal Code | 2.5.4.17 | urn:oid:2.5.4.17 |
Country | 2.5.4.6 | urn:oid:2.5.4.6 |
Profile Example
If your IQA returns the following information:
id | given_name | family_name | birthday | |
---|---|---|---|---|
10015475 | Alice | Sample | asample@example.org | |
Your SAML attributes would look like this:
<saml:Attribute Name="id" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
<saml:AttributeValue xsi:type="xs:string">10015475</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="given_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
<saml:AttributeValue xsi:type="xs:string">Alice</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="family_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
<saml:AttributeValue xsi:type="xs:string">Sample</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
<saml:AttributeValue xsi:type="xs:string">asample@example.org</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="birthdate" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
<saml:AttributeValue xsi:type="xs:string"/>
</saml:Attribute>
Profile Example using OID Naming
If your IQA returns the following information:
urn:oid:2.5.4.42 | urn:oid:2.5.4.4 | urn:oid:0.9.2342.19200300.100.1.3 |
---|---|---|
Alice | Sample |
Your SAML attributes would look like this:
<saml:Attribute Name="urn:oid:2.5.4.42" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
<saml:AttributeValue xsi:type="xs:string">Alice</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="urn:oid:2.5.4.4" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
<saml:AttributeValue xsi:type="xs:string">Sample</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="urn:oid:0.9.2342.19200300.100.1.3" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
<saml:AttributeValue xsi:type="xs:string">asample@example.org</saml:AttributeValue>
</saml:Attribute>