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:


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": "" 
		"Type": "duo", 
		"Name": "Secrets Safe Duo", 
		"Options": { 
			"IntegrationKey": "secrets safe integration key", 
			"SecretKey": "dss-secret-key", 
			"Host": "" 

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, 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:


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:


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.



	"type": "duo", 
	"name": "My company Duo application", 
	"options": { 
		"IntegrationKey": "qeetyitqrtqkjpohgdjag03?=", 
		"SecretKey": "j#lfae2df$?==", 
		"Host": "" 

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.

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

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:


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.