Multi-Factor Authentication Configuration
Multi-factor authentication (MFA) is supported in DevOps Secrets Safe by defining MFA configurations and then associating DevOps Secrets Safe principals with those configurations, and the corresponding identities, in remote MFA providers.
- Manage MFA Configurations
- Supported Multi-factor Authentication Providers
- Manage Multi-factor Authentication for Principals
- Log In as a Principal With Multi-factor Authentication Enabled
Manage MFA Configurations
/system/multi_factor
List Multi-factor Authentication Provider Configurations
ssrun mfa get
This command returns a JSON array of all MFA provider configurations.
$ ssrun mfa get [ { "Type": "duo", "Name": "BeyondTrustDuo", "Options": { "IntegrationKey": "my integration key", "SecretKey": "my-secret-key", "Host": "api-myorg.duosecurity.com" } }, { "Type": "duo", "Name": "Secrets Safe Duo", "Options": { "IntegrationKey": "secrets safe integration key", "SecretKey": "dss-secret-key", "Host": "api-dss.duosecurity.com" } } ]
Create Multi-factor Authentication Provider Configuration
ssrun mfa create -f myConfig.json
This creates the MFA configuration described in the file myConfig.json.
For valid configuration samples, please see Supported Multi-factor Authentication Providers.
Update Multi-factor Authentication Provider Configuration
ssrun mfa update -f updatedConfig.json -n <my_configuration_name>
Updates the MFA configuration with the contents of the configuration file:
updatedConfig.json
The name field for a configuration is static and cannot be changed by an update operation. All other fields are eligible for modification.
Delete Multi-factor Authentication Provider Configuration
ssrun mfa delete -n <my_configuration_name>
<my_configuration_name>.
Supported Multi-factor Authentication Providers
This section contains configuration options and sample usages of supported MFA providers.
All provider configurations require the following top-level items:
- Name: The name of the configuration. This must be unique across all MFA configurations.
- Type: The provider type.
Currently, only Duo is supported.
The configuration for the provider type is described below.
Duo
{ "type": "duo", "name": "My company Duo application", "options": { "IntegrationKey": "qeetyitqrtqkjpohgdjag03?=", "SecretKey": "j#lfae2df$?==", "Host": "api-my-company.duosecurity.com" } }
Options for Duo are:
- Host: (String, required). URL for the Duo applications authentication API.
- IntegrationKey: (String, required). The Duo application integration key to be used.
- SecretKey: (String, required). The Duo application secret key.
TOTP
DSS supports generic TOTP that can be used with any TOTP provider that adheres to RFC 6238, such as Google Authenticator. Because TOTP is symmetric and both parties hold a shared secret key, each principal has its own secret key provided when running ssrun mfa assign-principal. Optionally, you can omit the -m in ssrun mfa assign-principal and a TOTP secret is generated and assigned to the principal as well as returned from the command.
TOTP configurations are very simple, requiring only a name with the type totp.
Sample TOTP multi-factor authentication configuration:
{ "type": "totp", "name": "TotpDemoConfig" }
Manage Multi-factor Authentication for Principals
The following section describes how to manage MFA configurations for principals. A principal can have one or zero MFA providers configured. Only principals of type user or application support MFA.
Assign a Duo multi factor authentication configuration to a principal
ssrun mfa assign-principal -p principal/internal/user/bob -m 12752112652d3c0f21551938864e2 -c MyDuoConfig
This assigns MyDuoConfig to the internal user bob, who has the Duo ID 12752112652d3c0f21551938864e2.
Assign a TOTP multi-factor authentication configuration to a principal
ssrun mfa assign-principal -p principal/internal/user/bob -c totp_demo_config -m JBSWY3DPEHPK3PXP
This assigns TotpDemoConfig to the internal user bob, with the secret key JBSWY3DPEHPK3PXP.
Assign a TOTP multi-factor authentication configuration to a principal with a generated secret key
ssrun mfa assign-principal -p principal/internal/user/bob -c totp_demo_config -> totp enabled for principal principal/internal/user/bob using secret key S3C2LWXLMVBQHHU3
This generates a secret key S3C2LWXLMVBQHHU3 and assigns TotpDemoConfig to the user bob, using the generated key
ssrun mfa assign-principal -p principal/internal/user/bob -c totp_demo_config -m JBSWY3DPEHPK3PXP
This assigns TotpDemoConfig to the internal user bob, with the secret key JBSWY3DPEHPK3PXP.
Remove multi-factor authentication configuration from a principal
ssrun mfa remove-principal -p principal/internal/user/bob
This removes any multi-factor authentication for the internal user bob.
Log In as a Principal With Multi-factor Authentication Enabled
The following section describes how a principal with multi-factor authentication enabled can log in.
ssrun login -u bob -m 77552
The code above issues a login request for internal user bob using the MFA passscode provided by the multi-factor authentication provider.
Provider-specific Login Functionality
The following describes MFA login functionality that is specific to the provider type:
Duo
Authentication with Duo supports pushing notifications directly to devices that support push notifications and have the Duo application installed. To use this functionality, pass the push keyword as the MFA passcode on login:
ssrun login -u bob -m push
The above attempts to login as internal user bob and send a push notification to an eligible device. At that time the user can either accept or reject the authentication using their Duo application.