Attributes reference

You use SMS OTP to authenticate your end-users with a one-time password (OTP) sent to their phone by SMS. After authentication, you can receive their phone number.

This page shows scopes, attributes and response examples for each authentication protocol.

OIDC scopes and claims

OIDC scopes enable your application to specify the desired set of user data for each authentication.

Scope	Claim	Description	Example
`openid`	`idp_issuer`	The IdP used during authentication.	`otp-sms`
`idp-id`	`idp_id`	The phone number of the user.	`+447700900000`

Advanced configuration

ACR values

In OIDC, the acr_values query parameter lets your application specify the authentication context requirements for end-user authentication.

When building the OIDC authentication request for SMS OTP, the following keys apply:

Key	Description	Value example
`idp`	Defines which IdP to use. This works in conjunction with `login_hint`.	`otp-sms`
`otp_sms_sender`	Overrides the SMS sender name displayed to the recipient. The value cannot contain spaces; use a double underscore instead.	`Signicat__AS`

More information about acr_values

To learn more about generic acr_values that you can use in authentication requests to Signicat, see the acr_values reference page.

Set the UI language

To change the language on the SMS OTP UI, use the query string parameter ui_locales in the OIDC authorization request. For example, use ui_locales=gr to set the SMS OTP UI to Greek.

SMS OTP supports the following languages in ISO 639-1 format:

Language	Parameter
Danish	`da`
Dutch	`nl`
English (default)	`en`
Finnish	`fi`
Greek	`el`
Norwegian	`no`
Swedish	`sv`

Note: English is the default language.

Examples

OIDC request example

To trigger an authentication, you build an OIDC request like:

https://<YOUR_SIGNICAT_DOMAIN>/auth/open/connect/authorize?
    &client_id=<OIDC_CLIENT_ID>
    &response_type=code
    &redirect_uri=<REDIRECT_URI>
    &state=1599045135410-jFe
    &scope=openid%20idp-id
    &acr_values=idp:otp-sms
    &prompt=login
    &ui_locales=en
    &nonce=1599046102647-dv4

OIDC response example

Below, you find an example of a response example for the UserInfo endpoint.

Scopes in request: openid, idp-id

Response example:

{
    "idp_id":"+447700900000",
    "sub":"TOuh-Q-Qx2-EBXT3a3OgaoGXgQSx55ggpIym7PNOg=",
    "idp_issuer":"otp-sms"
}

Signicat Authentication REST API attributes

The Signicat Authentication REST API supports the following request and response attributes for SMS OTP:

Attributes	Example	Description
`idpId`	`+447700900000`	The phone number of the user.

Additional parameters

When sending requests to the Signicat Authentication REST API, you can customise end-user authentication with the additionalParameters field. The key-values you define in the additionalParameters field vary depending on the ID method.

SMS OTP supports the following parameters:

Key	Description	Value example
`otp_sms_sender`	Overrides the SMS sender name displayed to the recipient for a specific request.	`Signicat AS`

Example in a request payload:

    ...
    {
    "additionalParameters": {
        "otp_sms_sender": "Signicat AS"
    }
    }
    ...

Set the UI language

To change the language on the SMS OTP UI, use the language parameter in the payload of your request to the CreateSession endpoint. For example, use "language": "gr" to set the SMS OTP UI to Greek.

SMS OTP supports the following languages in ISO 639-1 format:

Language	Parameter
Danish	`da`
Dutch	`nl`
English (default)	`en`
Finnish	`fi`
Greek	`el`
Norwegian	`no`
Swedish	`sv`

Note: English is the default language.

Examples

Authentication API request example

To create a session using the Authentication REST API, you send a POST request to the CreateSession endpoint. This is https://api.signicat.com/auth/rest/sessions.

You define the parameters of the session in the payload of the request. For example:

{
    "allowedProviders": [
        "otp-sms"
    ],
    "flow": "redirect",
    "language": "en",
    "requestedAttributes": [
        "idpId",
	],
    {
        "additionalParameters": {
            "otp_sms_sender": "Signicat AS"
    },
    }
    "callbackUrls": {
        "success": "https://example.com/success",
        "abort": "https://example.com/abort",
        "error": "https://example.com/error"
	}
}

Authentication API response example

The following is an example of a response:

{
    ...
    "id": "4ccb8a1b-6f40-e146-af1b-15f1c6eabb56",
    "status": "SUCCESS",
    "provider": "otp-sms",
    "subject": {
        "id": "TOuh-Q-Qx2-XXXXXXXXXXXX",
        "idpId": "+447700900000",
    }
    ...
}

SAML 2.0 attributes

SAML 2.0 Protocol Attribute	Example	Description
`idpId`	`+447700900000`	The phone number of the user.

Additional attributes

Apart from regular requested attributes, the AuthnRequest to Signicat may contain additional parameters in the Extensions in the form of RequestedAttributes. To process these, the name of the RequestedAttribute should be of the form signicat:param:parametername. These can optionally contain a string type value.

With SMS OTP, you can override the SMS sender name displayed to the recipient:

SAML 2.0 Requested Attribute	Example	Description
`otp_sms_sender`	`Signicat AS`	Overrides the SMS sender name displayed to the recipient for a specific request.

For example, the request would contain:

<saml2p:Extensions xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol">
    <req-attr:RequestedAttributes xmlns:req-attr="urn:oasis:names:tc:SAML:protocol:ext:req-attr">
        <md:RequestedAttribute xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
                                Name="signicat:param:otp_sms_sender"
                                isRequired="true"
                                >
            <saml2:AttributeValue xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion"
                                  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                                  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                                  xsi:type="xsd:string">Signicat AS</saml2:AttributeValue>
        </md:RequestedAttribute>
    </req-attr:RequestedAttributes>
</saml2p:Extensions>

Response example

<?xml version="1.0" encoding="UTF-8"?>
<saml2p:Response xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol" Destination="..." ID="..." InResponseTo="..." IssueInstant="2023-08-18T13:21:19.716Z" Version="2.0">
  <saml2:Issuer xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">https://*YOUR_SIGNICAT_DOMAIN*/auth/saml</saml2:Issuer>
  <saml2p:Status>
    <saml2p:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
  </saml2p:Status>
  <saml2:Assertion xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:xsd="http://www.w3.org/2001/XMLSchema" ID="_59c600d2f1f8695fd2b837c6f0be0faf" IssueInstant="2023-07-18T13:21:19.736Z" Version="2.0">
    <saml2:Issuer>https://*YOUR_SIGNICAT_DOMAIN*/auth/saml</saml2:Issuer>
    <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
      <ds:SignedInfo>
        <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
        <ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
        <ds:Reference URI="#_59c600d2f1f8695fd2b837c6f0be0fss">
          <ds:Transforms>
            <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
            <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">
              <ec:InclusiveNamespaces xmlns:ec="http://www.w3.org/2001/10/xml-exc-c14n#" PrefixList="xsd"/>
            </ds:Transform>
          </ds:Transforms>
          <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
          <ds:DigestValue>...</ds:DigestValue>
        </ds:Reference>
      </ds:SignedInfo>
      <ds:SignatureValue>SIGNATURE_VALUE</ds:SignatureValue>
      <ds:KeyInfo>
        <ds:X509Data>
          <ds:X509Certificate>X509_CERTIFICATE</ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
    </ds:Signature>
    <saml2:Subject>
      <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified" NameQualifier="smt-otp">OZWWk8DKdFYf1JzLU8zJtku0uXkPaLvnIt</saml2:NameID>
      <saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
        <saml2:SubjectConfirmationData InResponseTo="_2d3e23bb30673b750e73e1f4e5b89f8e" NotOnOrAfter="2023-08-18T13:23:19.736Z" Recipient="RECIPIENT"/>
      </saml2:SubjectConfirmation>
    </saml2:Subject>
    <saml2:Conditions NotBefore="2023-08-18T13:21:14.737Z" NotOnOrAfter="2023-08-18T13:23:19.737Z">
      <saml2:AudienceRestriction>
        <saml2:Audience>ENTITY_ID</saml2:Audience>
      </saml2:AudienceRestriction>
    </saml2:Conditions>
    <saml2:AttributeStatement>
      <saml2:Attribute Name="idpId">
        <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xsd:string">+447700900000</saml2:AttributeValue>
      </saml2:Attribute>
    </saml2:AttributeStatement>
    <saml2:AuthnStatement AuthnInstant="2023-08-18T13:21:19.737Z" SessionIndex="XXXXXXX-fdff-47c9-b65f-XXXXXXX">
      <saml2:AuthnContext>
        <saml2:AuthnContextClassRef>substantial</saml2:AuthnContextClassRef>
        <saml2:AuthenticatingAuthority>otp-sms</saml2:AuthenticatingAuthority>
      </saml2:AuthnContext>
    </saml2:AuthnStatement>
  </saml2:Assertion>
</saml2p:Response>

OIDC scopes and claims​

Advanced configuration​

ACR values​

Set the UI language​

Examples​

OIDC request example​

OIDC response example​

Signicat Authentication REST API attributes​

Additional parameters​

Set the UI language​

Examples​

Authentication API request example​

Authentication API response example​

SAML 2.0 attributes​

Additional attributes​

Response example​

OIDC scopes and claims

Advanced configuration

ACR values

Set the UI language

Examples

OIDC request example

OIDC response example

Signicat Authentication REST API attributes

Additional parameters

Set the UI language

Examples

Authentication API request example

Authentication API response example

SAML 2.0 attributes

Additional attributes

Response example