OIDC Local Management Interface (LMI) Authentication

By default, management interface administrator accounts for IBM Verify Identity Access (IVIA) are limited to accounts local to the deployment (or LDAP). With the 10.0.0.0 Release of IVIA, administrators can integrate with external identity providers which follow the OIDC 2.0 specification.

This article will demonstrate how you can perform RBAC for external accounts as well as perform custom token mapping, if required.

The deployment we are managing is expecting that some users need read access to parts of the management interface occasionally, and a small number of users need write access.

We will also cover a use case where a small group of machine identities either want to perform scheduled maintenance during particular time periods, or be given permission to publish snapshot configurations.

Prerequisites:

• External Identity Provider (including group membership, or use custom JavaScript token mapping)
  • client identifier
  • client secret
  • PKI for TLS connection + token verification (if not using jwks)
• Running Verify Identity Access Management Interface.
  • article documents graphical interface procedure
  • configuration examples for automating deployment are provided here
• Implement any required authentication policies
  • This article will focus on how an identity mapped from a token can be used in a IVIA LMI. Multi-factor authentication should be implemented by the identity provider.

Disaster recovery:

If your management interface (or OIDC provider) becomes unresponsive, it is possible to connect to a command line interface (console or SSH) as the local admin account, and reset authentication. To do this, authenticate to the IVIA CLI, then run the command
lmi reset_lmi_authn
(you will be asked to confirm rebooting the appliance)

Once the management interface has been restarted, it will revert to the default local user registry.

Note: rollback is not possible in container environments once a configuration snapshot is published. Administrators should ensure they have backups of configuration snapshots before deploying OIDC SSO to the management interface.

Management Interface Configuration:

1. In the System -> SSL Certificates menu, import the required X509 certificates into the lmi_trust_store SSL Database as a signer certificate:
   
2. In the System -> Account Management menu, add in the names of the groups from your identity provider which define administrator (write access) users, in this example I am using the user adminUser. We also need to define the read access group adminGroup , in this example, write access admins are expected to be a member of both groups, if this is not possible then you can use token mapping to define custom logic :
   
   
   
   
   [Advanced] This can be extended further to allow for role based users/groups. Examples of this include: the cfgsvc user who is permitted to publish new configuration snapshots; or use the adminUser account as a catch-all user for impersonating a read-only access admin user.
   Administrators have the option of account impersonation using a custom token mapping function in combination with the management authorization feature to manage both known and unknown users. See the following Advanced section for example JavaScript token mapping code.
   
   
3. In the System -> Management Authorization menu, enable the Authorization Roles checkbox; select the Full Write role, select the Local User Database tab, in the list of user names, click edit and add in the user you created in the previous step, the admin user is here by default. Do the same for the Full Read role and the read access group:
   
   
   
   
   
4. In the System -> Management Authentication menu, select the Federated SSO option, select the OpenID Connect Client tab, then enter the OIDC confidential client details. For this example any user who has a valid token is an admin user (we will use the local groups/roles we just created for any required RBAC):
   
5. Deploy the changes
   WARNING: Once OIDC SSO is enabled, is is not possible to use any other form of authentication to the LMI. If access to the LMI is lost, Administrators can use a Terminal/SSH session to reset LMI authentication
   
   

[Advanced] Custom JavaScript token mapping:

If required, a custom JavaScript fragment (script) can be used to map the received identity token to user and group names. A simple example of this is the default option of all users are admin users. In this case, all valid identity tokens (the token is verified before your JavaScript is run) would be added to the adminGroup group. Users who require write access are mapped to their known local database identity (with appropriate management authorization membership for the local user).

It is important to note again that the group membership in this token cannot be used for RBAC. Therefore we are going to modify the username for a valid token to one that exists within the management interface's local user registry. Unknown users are mapped to the catch-all adminUser local identity, which has previously been assigned the Full Read role.

An JavaScript code fragment to implement this might look like:

function mapToken(operation, token) {
    if (operation === "mapToUser") {
        var sub = ''+token.get('sub');
        if ((sub == 'admin') or (token.get('principalName') in ["lgleeson@ibmsec.com", "admin@localhost"])) {
            return 'admin'; // local user given Full Write mgmt authz role.
        }
        return 'adminUser'; // mapped to Full Read mgmt authz role.
    } else {
        return ["adminGroup"]  //required group membership
    }
}

Role Based Access Control:

With the above configuration, admin users are split into two groups: one group of users who have read access to the IVIA LMI; and a group who has write access. We also a have a special group of users who are database administrators, and are only allowed to run specific High-Volume Database cleanup tasks.

The screenshots show the difference in LMI (and API) available to each group:

Identity providers also have the option of implementing multi-factor authentication (OTP/Passkey/MMFA) policies for administrators using an identity provider like IBM Verify:

API Client Authentication:

API client can still authenticate to the IVIA LMI with access tokens. If an admin user is able to acquire a valid access token, the token can be included in requests as a Bearer authorization header:

curl -kv -H 'Accept: application/json' -H 'Authorization: Bearer {token_goes_here}' https://{appliance}/core/sys/versions