Rate this page

TOTP Shared Secret

The totpSharedSecret SCIM sub-resource is used for generating or clearing a user’s shared secret for time-based one-time password (TOTP) authentication, or to simply determine if such a secret has been registered for the user.

Create a user’s TOTP shared secret

POST /scim/v2/Users/{id}/totpSharedSecret

POST /scim/v2/Me/totpSharedSecret

To generate a new TOTP shared secret, a client sends an empty POST request to a user’s totpSharedSecret sub-resource. The response will include a generated shared secret, as well as an otpAuthUri field that can be used to generate a QR code for use with the user’s TOTP device or app.

The response includes the following fields:

Field Type Provided? Description
schemas array always The SCIM schema of the TOTP shared secret resource. Always has the value urn:pingidentity:scim:api:messages:2.0:TOTPSecretRegistrationRequest.
meta complex always Will always contain a resourceType sub-attribute with the value TOTP Shared Secret. Will always contain a location attribute with the TOTP shared secret resource’s canonical URI.
sharedSecret string always The generated shared secret, encoded using Base32.
otpAuthUri string always A URI containing the generated shared secret, which can be encoded in a QR code and scanned by the user’s TOTP device. The URI is based on the Google Authenticator key URI format. This URI will always include a secret parameter with the Base32-encoded shared secret and an issuer parameter with a configurable identifier for the Data Governance Broker.
verifyState string always An internal state value used during the shared secret registration process. Must be returned when confirming the shared secret.
registered boolean always Whether or not a shared secret is registered for the user.

At this point, the shared secret will not yet be saved to the user’s account. The user must now prove that the shared secret has been correctly added to his or her device by providing a valid TOTP, which the client must submit to the Data Governance Broker via a PUT request along with the verifyState value received in the POST response.

Example request:

POST /scim/v2/Users/473d10ec-091b-4d89-bb59-1495f31da858/totpSharedSecret HTTP/1.1
Accept: application/scim+json
Authorization: Bearer eyJhbGciOi...
Content-Length: 94
Content-Type: application/scim+json
Host: example.com:443

{
    "schemas": [
        "urn:pingidentity:scim:api:messages:2.0:TOTPSecretRegistrationRequest"
    ]
}

Example response:

HTTP/1.1 201 Created
Content-Length: 519
Content-Type: application/scim+json
Date: Mon, 25 Jul 2016 23:38:31 GMT
Location: https://example.com:443/scim/v2/Users/473d10ec-091b-4d89-bb59-1495f31da858/totpSharedSecret

{
    "meta": {
        "location": "https://example.com:443/scim/v2/Users/473d10ec-091b-4d89-bb59-1495f31da858/totpSharedSecret", 
        "resourceType": "TOTP Shared Secret"
    }, 
    "otpAuthUri": "otpauth://totp/Broker:user.1?secret=GVWRD4K232MER5Q6WVBDGZBPLV6GEZL6&issuer=Broker", 
    "registered": false, 
    "schemas": [
        "urn:pingidentity:scim:api:messages:2.0:TOTPSecretRegistrationRequest"
    ], 
    "sharedSecret": "GVWRD4K232MER5Q6WVBDGZBPLV6GEZL6", 
    "verifyState": "Adco5hywdxeZ35ZsMmFYBVHNdyZsAAAAAAAAAACLbBaHdHRjSCG7LBPun7Zr8KrgifzHRUUMbn7DRNiT71m9YlYQMCrk7Was91o52Bw"
}

Confirm a user’s TOTP shared secret

PUT /scim/v2/Users/{id}/totpSharedSecret

PUT /scim/v2/Me/totpSharedSecret

Using the shared secret generated by a POST request, the user must prove that the shared secret has been correctly added to his or her device by providing a valid TOTP. The client must then submit a PUT request to the Data Governance Broker with the TOTP in the verifyTotp field, along with the previously received verifyState value. If this is successful, then the shared secret will be saved and may be used for subsequent TOTP authentications.

The request contains the following fields:

Field Type Required? Description
schemas array yes The SCIM schema of the TOTP shared secret resource. Always has the value urn:pingidentity:scim:api:messages:2.0:TOTPSecretRegistrationRequest.
meta complex yes Should always contain a resourceType sub-attribute with the value TOTP Shared Secret. Should always contain a location attribute with the TOTP shared secret resource’s canonical URI.
sharedSecret string yes The generated shared secret encoded in Base32.
otpAuthUri string A URI containing the generated shared secret, which can be encoded in a QR code and scanned by the user’s TOTP device. The URI is based on the Google Authenticator key URI format. This URI will always include a secret parameter with the Base32-encoded shared secret and an issuer parameter with a configurable identifier for the Data Governance Broker.
registered boolean Whether the shared secret is registered. This value will be ignored.
verifyTotp string yes A TOTP generated from the shared secret using the user’s TOTP device or app. This is used to verify that the shared secret was successfully registered with the device.
verifyState string yes An internal state value used during the shared secret registration process. Must be returned when confirming the shared secret.

The response contains the following fields:

Field Type Provided? Description
schemas array always The SCIM schema of the TOTP shared secret resource. Always has the value urn:pingidentity:scim:api:messages:2.0:TOTPSecretRegistrationRequest.
meta complex always Will always contain a resourceType sub-attribute with the value TOTP Shared Secret. Will always contain a location attribute with the TOTP shared secret resource’s canonical URI.
registered boolean always Whether or not a shared secret is registered for the user.

Example request:

PUT /scim/v2/Users/473d10ec-091b-4d89-bb59-1495f31da858/totpSharedSecret HTTP/1.1
Accept: application/scim+json
Authorization: Bearer eyJhbGciOi...
Content-Length: 629
Content-Type: application/scim+json
Host: example.com:443

{
    "meta": {
        "location": "https://example.com:443/scim/v2/Users/473d10ec-091b-4d89-bb59-1495f31da858/totpSharedSecret", 
        "resourceType": "TOTP Shared Secret"
    }, 
    "otpAuthUri": "otpauth://totp/Broker:user.1?secret=GVWRD4K232MER5Q6WVBDGZBPLV6GEZL6&issuer=Broker", 
    "registered": false, 
    "schemas": [
        "urn:pingidentity:scim:api:messages:2.0:TOTPSecretRegistrationRequest"
    ], 
    "sharedSecret": "GVWRD4K232MER5Q6WVBDGZBPLV6GEZL6", 
    "verifyState": "Adco5hywdxeZ35ZsMmFYBVHNdyZsAAAAAAAAAACLbBaHdHRjSCG7LBPun7Zr8KrgifzHRUUMbn7DRNiT71m9YlYQMCrk7Was91o52Bw", 
    "verifyTotp": "728650"
}

Example response:

HTTP/1.1 200 OK
Content-Length: 250
Content-Type: application/scim+json
Date: Mon, 25 Jul 2016 23:41:48 GMT

{
    "meta": {
        "location": "https://example.com:443/scim/v2/Users/473d10ec-091b-4d89-bb59-1495f31da858/totpSharedSecret", 
        "resourceType": "TOTP Shared Secret"
    }, 
    "registered": true, 
    "schemas": [
        "urn:pingidentity:scim:api:messages:2.0:TOTPSecretRegistrationRequest"
    ]
}

Retrieve a user’s TOTP shared secret state

GET /scim/v2/Users/{id}/totpSharedSecret

GET /scim/v2/Me/totpSharedSecret

A client may perform an HTTP GET to confirm that a shared secret exists for the user.

A TOTP shared secret resource contains the following fields:

Field Type Provided? Description
schemas array always The SCIM schema of the TOTP shared secret resource. Always has the value urn:pingidentity:scim:api:messages:2.0:TOTPSecretRegistrationRequest.
meta complex always Will always contain a resourceType sub-attribute with the value TOTP Shared Secret. Will always contain a location attribute with the TOTP shared secret resource’s canonical URI.
registered boolean always Whether or not a shared secret is registered for the user.

Example request:

GET /scim/v2/Users/473d10ec-091b-4d89-bb59-1495f31da858/totpSharedSecret HTTP/1.1
Accept: application/scim+json
Authorization: Bearer eyJhbGciOi...
Content-Type: application/scim+json
Host: example.com:443

Example response:

HTTP/1.1 200 OK
Content-Length: 250
Content-Type: application/scim+json
Date: Mon, 25 Jul 2016 23:42:49 GMT

{
    "meta": {
        "location": "https://example.com:443/scim/v2/Users/473d10ec-091b-4d89-bb59-1495f31da858/totpSharedSecret", 
        "resourceType": "TOTP Shared Secret"
    }, 
    "registered": true, 
    "schemas": [
        "urn:pingidentity:scim:api:messages:2.0:TOTPSecretRegistrationRequest"
    ]
}

Clear a user’s TOTP shared secret

DELETE /scim/v2/Users/{id}/totpSharedSecret

DELETE /scim/v2/Me/totpSharedSecret

A client may clear a user’s TOTP shared secret using the DELETE method.

Example request:

DELETE /scim/v2/Users/473d10ec-091b-4d89-bb59-1495f31da858/totpSharedSecret HTTP/1.1
Accept: application/scim+json
Authorization: Bearer eyJhbGciOi...
Content-Length: 0
Content-Type: application/scim+json
Host: example.com:443

Example response:

HTTP/1.1 204 No Content
Date: Mon, 25 Jul 2016 23:43:19 GMT