Description
To set up a new Multi-Factor Authentication (MFA) channel in your DruID account, use this method.
Please note that this method verifies user credentials beforehand. Consequently, an error response may be received from the login endpoint if the user’s credentials are incorrect.
Once you have successfully configured a new MFA channel, confirmation is required by sending a valid code through the validate code endpoint.
If you have previously generated an MFA channel but need to update certain information about the method, make a call to the update endpoint. In this scenario, ensure to provide a valid access_token for the requested user.
Endpoint URL:
POST https://{your-endpoint-domain.com}/activityid/v1/mfa/create
Request parameters
| Parameter | Description | Type | Required |
|---|---|---|---|
| Authorization | “Bearer app_token” Literal text Bearer followed by app_token that is the token obtained from /oauth2/token endpoint | string | yes |
| Content-Type | The type of content that will be used for requests to be JSON | string | yes |
| Accept | The type of content that will be used for responses to be JSON | string | yes |
| From | Name of the entry point | string | yes |
| Accept-Language | Language for this request | Locale | no |
Query string parameters
| Parameter | Description | Type | Required | Default value |
|---|---|---|---|---|
| sc | With this paramater you can configure how user fields are validated: by default ALL validation errors are returned back to service caller (). If you want to receive only ONE validation error each time, you have to send query String parameter ‘sc=true’ | boolean | no | false |
| fca | Force to check complete account after successful login. If user needs to complete data you will receive same response defined in complete account error each time, you have to send query String parameter ‘sc=true’ | boolean | no | false |
Request Example
| Parameter | Description | Type | Required | Value |
|---|---|---|---|---|
| actor.id | app_id of the application you are using to log user | string | yes | app id |
| actor.objectType | Type of the object which represents the actor. | string | yes | ‘application’ |
| verb | Verb used for the login | string | yes | ‘create’ |
| object.objectType | ObjectType represents the user | string | yes | ‘user’ |
| object.password | Password of the user. it must be send plain | string | yes | user password |
| object.ids.email | Structure of email identifier. node name must be “email” | struct | yes | |
| object.ids .email.objectType | ObjectType represents the id of the user | string | yes | ‘user_id’ |
| object.ids.email.value | Email value | string | yes | |
| source.id | Type of device doing the activity | string | yes | ‘unknown’ | ‘pc’ | ‘mobile’ | ‘tablet’ | ‘game_console’ | ‘itv’ |
| source.objectType | Type of source | string | yes | ‘device’ |
| context.mfa_channel | Name of the MFA channel | string | yes | ‘sms’ |
| context .mfa_channel_address | Address where to send the TOTP code. For instance, a phone number if the channel is SMS | string | no | ‘+34123123123’ |
Response examples
Response: MFA Created Channel
| Parameter | Description | Type |
|---|---|---|
| content | Data receive with the response | struct |
| content.provider | The provider that generates the TOTP codes. | string |
| content.isMandatory | Whether the MFA has been created with mandatory scope | string |
| content.channel | The name of the channel that has been configured. | string |
| content.secret | Secret shared with the user, this secret would be used as a seed for generating the TOTP codes. This is the code that is commonly requested in the authentication apps if the QR code is not available. | string |
| content.qrUri | The “otpauth” complete URI representing the MFA channel. | string |
| content.printableQrUri | The “content.qrUri” but encoded to be printed in html. You can print it with by pasting this property in the “src” on an “img” tag` | long |
| content.recoveryCodes | Codes used for recovering the account in the case that the user had lost all the MFA channels. This codes are generated only after the creation of the first MFA channel. | string |
| result | Common http result | struct |
| result.status | Http code | integer |
| result.message | A description that describes the result of the operation | string |
Response codes
| Code | Type | Description |
|---|---|---|
| 400 | Error | Bad Request: The request could not be understood by the server due to malformed syntax |
| 401 | Error | Unauthorized: authentication is required and has failed or has not yet been provided (token is invalid, etc) |
| 403 | Error | Forbidden: user id or password are invalid |
| 412 | Error | Precondition failed: User can not log because he/she has not confirmed email |
| 417 | Error | MFA Error: There is a problem with MFA, you will receive a detailed error description |
| 500 | Error | Internal Server Error: The server encountered an unexpected condition which prevented it from fulfilling the request |
| 504 | Error | Gateway TimeoutService can not contact with oauth server to do some internal operations |
| 200 | Success | MFA code configured succesfully |