User authentication¶

Setting AtoM group membership from CAS user attributes¶

AtoM CAS support can be optionally configured to automatically set each user’s AtoM user group membership based on the presence or absence of expected values in user attributes returned by a CAS server during authentication. When enabled, this entitlement check occurs on each login so that changes made to group membership on the CAS server are reflected in AtoM on the next login.

This feature is enabled via settings in the the arCasPlugin’s app.yml config file.

First, enable the feature by setting set_groups_from_attributes to true.

Next, set the CAS attribute whose values will be checked to determine group membership in attribute_key.

Finally, set the attribute_value of each group in user_groups to match the expected value for that group in the CAS attributes.

Groups can be added or removed from user_groups as desired. Only groups that are properly configured with an attribute_value and a valid group_id will be used to set AtoM group membership on login.

Back to top

Base DN and Bind Lookup Attribute - overview¶

These two elements are what AtoM will use to determine which LDAP entry the authentication attempt should be compared against.

The Base DN will provide AtoM with the common parts of an LDAP entry on your server that won’t change per user - basically, where to look in the LDAP directory tree to find general user information.

Every LDAP entry consists of a set of attributes. LDAP entries are stored in a tree-like directory structure, so the information provided in this field should give AtoM enough information to find the subdirectory that contains your unique users. Configuring this field in AtoM will require an understanding of how your LDAP server is configured.

Every LDAP entry will have a Distinguished Name (DN) that uniquely identifies that entry and its position in the directory information tree (DIT) hierarchy, similar to the path to a file on a filesystem.

Each LDAP DN is composed of zero or more elements called relative distinguished names (RDNs), and each RDN is composed of at least one attribute-value pairs. There are several commonly used attributes, such as:

• cn: Common name. For example, “John Doe”
• sn: Surname. For example, “Doe”
• uid: User ID. Because a DN indicates directory location, it’s possible a DN may change over the lifetime of the entry, for example if an entry is moved within the directory’s information tree hierarchy. Including a unique ID for each entry means this can be used in a DN. For example, jdoe01.
• dc: Domain component. For example, If the base domain name of the LDAP server is found at ldap.example.com, then the domain components for an entry might be dc=ldap,dc=example,dc=com with each part of the full domain being one domain component.
• mail: Email address associated with the entry. For example, `` john.doe@example.com``.
• ou: Organizational unit. Typically represents a directory used in your LDAP directory hierarchy, such as Users.
• userPassword: the password associated with the particular user defined in the LDAP entry.

There are a number of other attribute key-value pairs often used as well for capturing additional information about the entry and its location in the directory tree, but those listed above include the elements we need to configure AtoM’s Base DN.

Meanwhile, the Bind Lookup Attribute setting in AtoM will specify which attribute should be used to uniquely identify the user. This attribute value will tell AtoM which LDAP attribute to compare against the value entered into the “Email” field in AtoM’s login panel. While the Base DN values will be common to all LDAP entries, the attribute selected for Lookup should be unique. An example:

dn: uid=jdoe01,ou=atomUsers,dc=example,dc=com
    ^^^        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    Lookup     Base DN

When authenticating a user, AtoM will use the Base DN and Bind Lookup Attribute values together to identify the relevant target LDAP entry that is used for validating the authentication attempt. This means:

• Whatever is set as the Bind Lookup Attribute in AtoM’s settings should match what users logging in with LDAP will enter into the AtoM login panel’s “Email” field.
• Whatever password a user enters into the AtoM login panel’s “Password” field should match the userPassword value in their LDAP directory entry.

Configuring the Base DN and Bind Lookup Attribute settings¶

The Base DN setting in AtoM must include any ou (organizational unit) directory component that target users are contained in on the LDAP server, plus any domain components (dc) required to find the information. AtoM will use this to be able to find where individual LDAP entries are stored within the LDAP server’s directory tree. each attribute key/value pair should be entered separated by commas, with no spaces between them.

For example, if the target LDAP server has user accounts in an Organizational Unit called “atomUsers” on a server with a domain of example.com, then the Base DN setting in AtoM would be entered as:

ou=atomUsers,dc=example,dc=com

The Bind Lookup Attribute should be whatever attribute in your LDAP entries will be globally unique, unlikely to change, and used to identify individual users. If you want the login experience to match AtoM’s current expectations (using an email address in the username field) and your LDAP server is configured to use mail attributes for every user, then you would enter mail into this field.

If mail is not used in your LDAP server, uid is a good option, as this typically shouldn’t change even if the entry moves in the LDAP directory tree. Barring that, cn could be used. Whatever is picked will define what type of information end users attempting to authenticate in AtoM should enter into the login panel’s “Email” field.

In the above example, users would enter their LDAP username into AtoM’s “Email” field in the login menu. If cn were used as the lookup attribute instead, then users would need to enter their LDAP common name.

After configuring the LDAP settings¶

Once configured, users registered on the LDAP server should now be able to authenticate with their LDAP credentials to log into AtoM.

When a user authenticates for the first time, a new AtoM user is created in the database. However, by default, this user is not assigned to any user groups, and will therefore only have the base permissions of the Authenticated user group. An administrator can modify the user permissions after the new user has been created using AtoM’s permissions module - for more information, see:

• Edit permissions
• Manage user accounts and user groups

Enable the plugin¶

Create an empty file named activate-oidc-plugin in the root of the AtoM installation to enable the OIDC plugin. Permissions and ownership of this file should match the other folders in the AtoM folder.

Next, change the default login module to OIDC in apps/qubit/config/settings.yml.

Finally, change the user class to oidcUser in apps/qubit/config/factories.yml.

Configure the OIDC settings in the plugin’s app.yml file¶

Next, configure the OIDC settings in the arOidcPlugin’s app.yml config file with the details of the OIDC endpoint for authentication.

Update the providers array:

One or many OIDC providers can be configured in the app.yml. Each provider will have separate configuration for the following settings:

url

OIDC provider authentication redirect URL. This is the URL that you will be redirecting to. For example, if redirecting to Keycloak, it will look something like: https:///realms/<atom_realm_name>

client_id

The client identifier registered with the identity provider. This identifies a particular application instance authorized to connect to the OIDC provider for authentication services.

client_secret

The credential secret for the defined client.

primary_provider_name

Identifies the primary OIDC provider and corresponds to an entry in providers above. The default provider name is primary. If this setting is not defined, the default provider named primary will be set.

This is the provider that will be selected for authentication when a user selects “Log in with SSO”.

provider_query_param_name

This setting enables the use of additional providers and identifies the name of the query param that can be added to the referring URL when selecting “Log in with SSO” button. The use case for this functionality is to allow support accounts not included in the primary IAM endpoint authenticate.

To use, append the query param and the provider name to the URL before selecting “Log in with SSO”. This must be uncommented to activate use of secondary providers.

Ex. Use the sample_provider provider by modifying the URL before pressing “Log in with SSO”: http://127.0.0.1:63001/index.php?secondary=sample_provider

redirect_url

URL that Keycloak should redirect back to once the authentication process completes.

send_oidc_logout

This boolean value indicates to the OIDC plugin whether the IAM endpoint supports OIDC logout and this is safe to send. Keycloak supports this functionality so it is safe to send. For Dex, this should be set to false.

logout_redirect_url

Use this setting to configure the URL to redirect to on Logout. This parameter is only used if send_oidc_logout is true.

enable_refresh_token_use

Enables use of OIDC refresh tokens to periodically check-in with the IAM service to extend the user’s session and ensure it has not been ended.

When set to false, user will remain authenticated until the user ends the session in AtoM - in this case AtoM will not check if the session is still valid in the backend IAM system.

When set to true, AtoM will check in with the backend IAM system at intervals determined by the refresh token expiry setting in the IAM system (ex. Keycloak). This is dependent on a user actively using AtoM - an idle AtoM session will let the refresh tokens expire. Active sessions can be viewed and ended on the IAM side (ex. in Keycloak). AtoM will discover sessions have been ended the next time it refreshes the tokens.

server_cert

OIDC server TLS certificate location for server validation. Accepts a file path or false (to disable).

It is recommended to refer to an external file for the server_cert rather than pasting the cert value into app.yml.

It is also recommended to have the server_cert file NOT be located in the AtoM application folder in a production setting. If the server_cert file is located in the AtoM folder there is a risk that a misconfiguration in the nginx config could expose the server_cert to the network.

scopes

OIDC scopes are used by an application during authentication to authorize access to a user’s details, like name and email address.

set_groups_from_attributes

Setting to activate parsing OIDC groups into AtoM group membership. AtoM will attempt to translate OIDC groups to AtoM groups if true. When activated, AtoM will refresh a user’s groups in AtoM from the IAM system each time they login to ensure they are up-to-date.

If this setting is false, groups parsing will not occur and the user will only have the group authenticated on first log in. In this case, an AtoM admin will have to manually assign groups to the user after they authenticate the first time.

See Set user groups from OIDC groups for more information.

user_groups

This setting maps OIDC roles to AtoM groups. The data structure is as follows:

This entry maps the OIDC group atom-admin to the group administrator. The group_id is a database id - this value should not be changed for a default installation.

roles_source

This setting identifies the token which contains role claims. Options are access-token, id-token, verified-claims, or user-info. Option set_groups_from_attributes must be true to enable. Default is access-token.

roles_path

This setting identifies the location of role claims within the token identified in roles_source above. This is an array containing the node path to locate the roles array within the OIDC token. By default this is found in Keycloak’s access token under realm_access/roles.

user_matching_source

This setting identifies how IAM users are matched to users in AtoM. There are two valid options:

user_matching_source: oidc-email or user_matching_source: oidc-username

Using oidc-username will work without additional scopes being requested.

Using oidc-email requires the email scope to be set above in the scopes setting. Email is an optional user setup field in Keycloak but MUST be set if matching to pre-existing user accounts by email is going to work.

See Set user groups from OIDC groups for more information.

auto_create_atom_user

Activate or disable the automatic creation of user records from OIDC endpoint details. Allowed settings are:

true (default): AtoM will automatically create a user record on first login.

false: AtoM will not automatically create a user record on first login - user must be created in advance to successfully authenticate.

If this setting is false, the User settings page will allow users to be created and deleted. When this setting is true, the ability to create and delete users is suppressed - users will automatically be created from details received from the OIDC endpoint.

Clear the cache¶

After updating the settings listed above, clear the Symfony cache: php symfony cc and restart php-fpm.

Deactivating the OIDC plugin¶

Deactiviating the OIDC plugin is a matter of reversing the steps taken to enable the plugin.

First, delete the plugin name arOidcPlugin from the $plugins array in config/ProjectConfiguration.class.php.

Then, revert the default login module to its original value of user in apps/qubit/config/settings.yml.

Finally, revert the user class value to myUser in apps/qubit/config/factories.yml.

At this point, clear all caches and restart php-fpm.

Set user groups from OIDC groups¶

User groups can be configured automatically based on user groups returned by OIDC endpoint during authentication. When enabled, this entitlement check occurs on each login so that changes made to group membership on the IAM server are reflected in AtoM on the next login.

Enable via settings in the plugins/arOidcPlugin/config/app.yml:

First, enable the feature by setting set_groups_from_attributes to true.

Then, set the roles_source and roles_path to identify where to look for OIDC roles in the tokens returned from the OIDC enpoint. AtoM can be configured to look for role info in a few locations: access-token, id-token, verified-claims, or user-info

Finally, set the attribute_value of each group in user_groups to match the expected value for that group in the OIDC token. Groups can be added or removed from user_groups as desired. Proper configuration of attribute_value and a valid group_id are required to set group membership on login.

If set_groups_from_attributes is set to false, an administrator will need to manually assign and administer group membership for each user. OIDC authenticated users will, by default, only have the authenticated group membership.

Implications for user records created prior to activating OIDC plugin¶

Matching OIDC user info to existing users

AtoM user record must match the IAM user record. Set user_matching_source to either oidc-email or oidc-username. Mismatch will result in a new user record to be created.

Existing password and salt fields

Once the OIDC plugin is activated, existing password hashes stored in user records will no longer be used, but valid again if the OIDC plugin is deactivated. If it is desired that users should NOT be allowed to authenticate locally, the password hash and salt fields must be deleted or set to NULL in the database.

OIDC Cache Configuration¶

External cache is required for the correct operation of the OIDC plugin authentication flow. To configure an external cache, the storage class definition in factories.yml needs to be implemented in QubitCacheSessionStorage instead of QubitSessionStorage.

The default factories.yml storage definition is incompatible with the OIDC plugin authentication redirect pattern.

storage:
  class: QubitSessionStorage
  param:
    session_name: symfony
    session_cookie_httponly: true
    session_cookie_secure: true

Example using QubitCacheSessionStorage, demonstrating configuration for Memcache as backend.

storage:
  class: QubitCacheSessionStorage
  param:
    session_name: symfony
    session_cookie_httponly: true
    session_cookie_secure: true
    cache:
      class: sfMemcacheCache
      param:
        host: <memcache-host>
        port: <memcache-port>
        prefix: atom
        storeCacheInfo: true
        persistent: true

Example using QubitCacheSessionStorage to connect to APC cache backend.

storage:
  class: QubitCacheSessionStorage
  param:
    session_name: symfony
    session_cookie_httponly: true
    session_cookie_secure: true
    cache:
      class: sfAPCCache
      param:
        storeCacheInfo: yes
        prefix: atom-public
        host: <apc-host>
        port: <apc-port>
        persistent: yes

Back to top