Configuring Authentication Policy

This article covers the following topics:

• Enabling SAML add-on

• Creating a new authentication policy with 3 mechanisms

• Configuring the SAML credential mechanism

• Enabling the authentication policy

Note:

• To configure your SSO, always connect to the iObeya Platform Administration by using the public URL of the server.

• Accessing the platform through http://localhost for instance has to be avoided.

Enabling SAML add-on

To enable the SAML add-on:

1. Select Add-ons in the left-hand side of the menu of the administration interface.

2. Find the “saml-auth” add-on.

3. Verify that the saml-auth has an Enabled status, not Installed.

4. If the status is Installed, Click Enable to enable it.

   The “saml-auth” add-on is successfully enabled.

Creating a new authentication policy with 3 mechanisms

To create a new authentication:

1. Select Settings > Authentication policies in the left-hand side of the menu of the administration interface.

2. Click New Policy.

3. Give a name to your policy and validate.

   Your authentication policy is successfully added.

4. From the Authentication mechanism, you find the following 3 mechanisms:

   

   1. The SAML credential mechanism is for SSO.

      See Configuring the SAML credential mechanism to find out more.

      Note :

      If you put SAML credential mechanism first in the list, the SSO authentication flow is used by default without showing the iObeya “default login/password”.

      However, it would be possible to access the “default login/password form” by using the direct URL https://iObeya-server-URL/login (if you access iObeya using https://iObeya-server-URL), unless you have deactivated or removed the Form credential mechanism from your authentication policy.

   2. The Form credential mechanism is necessary if you want to keep the iObeya “default login/password” form. You can use the default values.

      See Adding and Configuring an authentication mechanism > Configuring a Form Authentication Mechanism of the Administration guide to find out more.

   3. The local user authentication mechanism is necessary to use local user accounts (for example: accounts created and managed in iObeya). You can use the default values.

      See Adding and Configuring an authentication mechanism > Adding and Configuring Local User Authentication Mechanism to the Policy of the Administration guide to find out more.

Configuring the SAML credential mechanism

To configure the SAML credential mechanism:

1. Access the configuration interface of the authentication policy.

2. Add the SAML authentication mechanism to your authentication policy.

   The following screen is displayed:

3. Give a name that are displayed on the login page.

4. Customize the look of the login page : set a text color and an icon color to illustrate your SAML provider.

   Note:

   It is useful to customize the login page when you use dual authentication with SAML and form mechanisms.

5. Configure the Metadata section.  

   

   1. Upload metadata file to access the file of the Identity Provider.

   2. Check “Generate the metadata for iObeya”.

      The EntityID of iObeya is not mandatory. If the field is empty by default, it will put the platform URL.

   Warning:

   You are not able to save that authentication mechanism if you do not provide a metadata file for the IdP:

   • If you already have the metadata of the Identity Provider (IdP), import it.

   • If you do not, you can ask us for a temporary dummy metadata file.

6. Configure the Key management section.

   Here are the basic example provided using the tool KeyTool.

   Based on these command lines, the keys have a validity of 1095 days.

   keytool -genkey -keystore myKeystore.jks -alias myKey -keyalg RSA -sigalg SHA256withRSA -keysize 2048 -validity 1095

   In that case, keyTool asks to type in:

   • Password for myKeystore.jks keystore

     • e.g. myKeystorePassword

   • Domain name details: name, organizational unit, enterprise, city, state, country code

   • The password for the myKey key,

     • e.g. myKeyPassword

   Then, in the iObeya “Key management form”, you need to import the keystore file you have just created:

   

   • Keystore password:

     • e.g. myKeystorePassword.

   • Passwords for the keys in the keystore (format: json object): {"myKey":"myKeyPassword"}

   • Name of the default key: myKey

   These parameters are described in the SSO parameters section > Keystore.

7. Fill out the Authentication attributes.

   During the authentication phase, the user gets authenticated on the IdP, and then the IdP sends a “SAML assertion” to iObeya. That assertion contains some information about the user that iObeya is going to use to compare it with its local accounts.

   For example, the user on the left is defined in the Enterprise Directory with his login, firstname, lastname, email, etc. And you need to configure the IDP so that it is going to send the right information to iObeya through the assertion.

   That information needs to be passed as attributes.

   

   Here is an example of an assertion (extract):

   

   In this example, the assertion contains 1 attribute: Its name is “UPN”, and its value is “jdoe”.

   On the iObeya side, you need to configure the “Authentication attributes” section accordingly:

   

   1. You specify what attribute name to look for.

      • e.g. “UPN”

   2. You specify if iObeya should compare that attribute’s value (e.g. “jdoe”) with the username or email of its local users.

   In the previous example, if iObeya finds an account in its database that has “jdoe” as username, then it is going to log that user in.

   Note:

   The “IdP Authentication Attribute Name” needs to be passed as an “attribute” in the assertion. iObeya cannot use the “subject” field passed in the assertion.

   Warning:

   If you use the email address to match the users, a part of (local part is, domain part is not) this authentication process is case-sensitive. Indeed, nobody should interpret the local part as it can only be understood by the domain owner (for example dots are ignored and match is case-insensitive for google accounts, but it might be different for another domain).

   For example, let say the user John Doe has “John.Doe@MyCompany.com” as email address in the Enterprise Directory.

   • If John Doe is declared in iObeya with “John.Doe@MyCoMPany.CoM”, then it would match

   • If John Doe is declared in iObeya with “john.doe@MyCompany.com”, then authentication fails and a warning is displayed in logs.

   Enable “Allow account creation” (optional)

   Note:

   If you want self-registration, you need to enable Allow account creation.

   With that option activated, if a collaborator does not have an account on iObeya, the first time he/she clicks on the SSO button on the iObeya login page:

   1. He/she gets authenticated on the IdP.

   2. The IdP sends all the necessary information to iObeya.

   3. iObeya creates the account using the information transmitted.

   4. The user is logged in on iObeya.

   In that case, you have to map iObeya’s fields to the attributes that are received, because iObeya needs to specify the username, the firstname, the lastname, and the email in order to create an account.

   For example, you could configure, in the IdP, the following attributes (which are passed in the assertion):

   

   You need to specify, in iObeya, what attribute name (yellow) to look for in the assertion, and where to map them (username, email, firstname, lastname).

   In that example, the following user would be created in iObeya:

   • Username: jdoe

   • Firstname: John

   • Lastname: DOE

   • Email: john.doe@iobeya.com

   

   Note:

   • In iObeya, if you want the username to be set as the email address of the IdP, you could use the same attribute name both for username and for the email address, in the iObeya configuration.

   • If you are configuring SSO for Azure AD, the usual attribute names that you can configure in your IdP, and that you should declare in iObeya are:

     • Username -> http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn

     • Firstname -> http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname

     • Lastname -> http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname

     • Email -> http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

   • If you are using the LDAP’s Object Identifiers - OID -, the usual attribute names that you can configure in your IdP, and that you should declare in iObeya are:

     • Username (uid) -> urn:oid:0.9.2342.19200300.100.1.1

     • Firstname (givenName) -> urn:oid:2.5.4.42

     • Lastname (sn) -> urn:oid:2.5.4.4

     • Email -> urn:oid:0.9.2342.19200300.100.1.3

8. Configure the Additional Settings section.

   Unless you have a specific configuration (see the SSO parameters), you can keep most of the default values, but:

   • You might want to increase the Maximum authentication age, especially if you get this error: “Response doesn't have any valid assertion which would pass subject validation”. With its default value (“7200”, i.e. 2 hours in version of iObeya < 4.5), if the user got authenticated on the IdP more than 2 hours ago, iObeya would consider that the authentication token is too old, and it would refuse to log that user in.

     • You could easily increase that value to 10 hours (“36000”) or even 20 hours (“72000”).

     • In most of the case, as more and more users use to never close their session, one uses huge figures in this section ; 8640000 is a value commonly used to be peaceful. This is the default value set in version of iObeya > 4.6.

9. Save the configuration.

10. Downloading the iObeya metadata

    Once this is done, reopen the SSO authentication policy you have just created:

    1. Move the cursor over your SSO authentication policy and click Edit information.

    2. Right-click on Download configured metadata in the Metadata for iObeya (SP).

    3. Use “Save link as…” option.

    4. Send the downloaded metadata XML file to the IDP administrator, so that they could import it into their IDP.

    Note:

    • Set the default RelayState to the iobeya home URL (https://[acme].iobeya.com)

    • Be aware that iObeya will not read Subject and NameID from the SAML response, it only reads what is in the attributes section. Therefore the values you want to send to additional parameters will have to be mapped correctly.

11. Uploading the IDP metadata

    Once the IDP administrator has uploaded the iObeya metadata into the IDP, and configured all the attributes/claims, the IDP administrator needs to download and send you the IDP metadata that you need to import in iObeya:

    

    Note:

    Make sure the attributes / claim names declared on the IDP are declared exactly the same on the iObeya side.

    Save the authentication policy.

12. Save the authentication policy.

Enabling the authentication policy

Once this is done, you just need to enable the Authentication Policy you have just created.

Warning:

It disconnects all the users currently connected, so they need to reconnect. It is best to plan it during non-business hours, and/or to inform the users (email, announcement in iObeya)

Note:

When you enable the new policy, a pop-up window is displayed with a URL. Please copy that URL and save it, as this is the fallback URL, in case you need to restore the default authentication policy.