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

Multi-factor authentication can be configured using the CLI or the API. Management permissions for MFA configurations are CRUD operations on the resource path:

/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>
Deletes the configuration named:

<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.