Authentication with MFA

It is possible to enable MFA when authenticating towards the system. There are two main ways to do this, either an OIDC provider can be used, in which case the MFA is handled by the OIDC provider, or a local userpass user. If a local user is configured using userpass then an OTP can be configured using TOTP.

Configuring OIDC

The OIDC login used by the system follows what is called the OpenID connect Code Flow. When a user attempts to login it is done through the oidc-login action. The action returns a redirect URL to the OpenID Provider. If the user is logging in through the terminal the user opens the URL in a browser, if going through the WEB-UI the user is redirected to the URL. If the OpenID Provider successfully authenticates the user, the user is redirected back to original system together with a code. The system then contacts the OpenID Provider and verifies the users code, if successful some user properties (claims) are returned to the system, which uses these to further verify the user before issuing a token.

To setup this service some information is needed from the OpenID Provider: discovery-url, client-id and client-secret. Optionally a discovery-ca-cert can be used if the OpenID Provider does not have a certificate that can be verified using the standard CA cert bundle.

The discovery-url is the URL to the OpenID Provider. The client-id is obtained from the OpenID Provider when registering a new OIDC client. The client-secret is a shared secret between the OpenID Provider and the client. It is also obtained when registering a new client with the OpenID Provider.

Using the above information an OIDC service can be configured, ie

supctl create strongbox authentication oidc-services <<EOF
name: curity
client-id: supd
client-secret: fAfo70mG8N0QRXvVYGyGYHlGO7dYyX1EGfip2tEMfHp8QyuOv-pqP15aY1zsHpSgO
discovery-url: https://oidc.acme.com/oauth/v2/oauth-anonymous
default-role: admin
EOF

In addition a redirect-url must be configured in the OpenID Provider to allow the session to be redirected back to the original system.

Also an oidc-service role must be configured. Different roles can be used to map users to different policies etc.

To configure the admin role for example

supctl create strongbox authentication oidc-services curity roles <<EOF
name: admin
allowed-redirect-uris:
  - https://supd.acme.com:4646/v1/oidc-callback
token-policies:
  - user
verbose-logging: true
claim-mappings:
  email: email
  name: username
EOF

The claim-mapping is used to map user claims to metadata in the issued token. The token-policies controls which policies will be associated with the issued token. There are multiple other options to control which users are allowed to login through the OpenID Provider, and how to assign policies.

Userpass

By default a user authenticating using the userpass service does not have to provide a one time password (OTP). However, there is an option for adding that requirement. To do this a TOTP instance for the user must first be configured in the system.

To setup a new TOTP instance for the user admin@telco.com

supctl create strongbox totp <<EOF
name: admin@telco.com
issuer: telco.com
account-name: admin@telco.com
EOF

Note that the account-name is only used as documentation for the user when the user imports the TOTP into, for example, the Google Authenticator application. The account-name is not a link to the userpass instance and may differ from the name of the userpass entry using the totp instance.

The TOTP instance can be viewed

supctl show strongbox totp admin@telco.com 
name: admin@telco.com
digits: 6
algorithm: sha1
key-size: 20
period: 30s
issuer: telco.com
account-name: admin@telco.com
skew: 1
passcode32: IG3UL5SUO3NWKMHIN42NE2V7PPHSBMS7
url: otpauth://totp/Sbox:admin%40telco.com?secret=IG3UL5SUO3NWKMHIN42NE2V7PPHSBMS7&issuer=telco.com
creation-time: 2022-09-28T09:29:27.734837Z

The url can be given to the user and entered into a client application like the Google Authenticator. It is also possible to generate a QR code that can be scanned by the application.

supctl do strongbox totp admin@telco.com get-qr-code
qr-code: iVBORw0...

The returned qr-code is a base64 encoded PNG image.

The TOTP instance can now be added to the admin@telco.com userpass account.

supctl merge strongbox authentication userpass admin@telco.com <<EOF
name: admin@telco.com
totp: admin@telco.com
EOF

When admin@telco.com attempts to login an TOTP OTP must be provided, eg.

supctl do login admin@telco.com --otp 375810
password: verysecret

If an TOTP OTP is required but not provided, the return will be an error TOTP required. A UI can look for this and provide an additional prompt for an OTP when this error is returned.

User enabled TOTP

It is possible to setup a userpass entry to let the user enable TOTP by themselves, and thus get access to the QR-code in the process. To support this a userpass entry is created with an additional setting of no-totp-token-policies, which is a list of policies that should be used until the user has enabled TOTP. This allows the user limited access and the intention is that it should allow the user to execute the enable-totp action. For example,

supctl create strongbox authentication userpass <<EOF
name: joe@telco.com
password: verysecret
no-totp-token-policies:
  - totp-enable

The totp-enable policy is a fairly restricted policy that allows the user to execute the action enable-totp, and enable-totp-verify among a few other things such as token-info and change-password.

The action strongbox authentication enable-totp will return the QR-code that the user needs. It creates the required TOTP service (with the same name as the user) and configure the totp leaf in the user's userpass instance. Note that the action can only be executed once. It will return an error on any subsequent invocation.

supctl do strongbox authentication enable-totp
qr-code: iVBORw0...

The returned qr-code is a base64 encoded PNG image.

Once enabled, the user cannot login without providing a OTP matching the TOTP and, once logged in, the token will get normal policies for the user.

The strongbox authentication enable-totp-verify action is similar to enable-totp, but it needs to be invoked twice. The first time the QR-code is returned. The user then needs to use that QR-code to generate an OTP and invoke the action again with the OTP as argument. This ensures that the user has been able to successfully register the QR-code in their authentication app before OTP is finally enabled.