For the complete documentation index, see llms.txt. You can also append .md to any page URL to get its markdown version.
Skip to main content
For the complete documentation index, see llms.txt.

For the complete documentation index, see llms.txt

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.

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:

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.

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%20phone
    &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, phone

Response example:

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

Signicat Authentication REST API attributes​

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

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

SMS OTP supports the following parameters:

Example in a request payload:

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

Examples​

Authentication API request example​

To create a session using the Authentication REST API, you send a POST request to the Create a new session 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",
        "phoneNumber"
	],
    {
        "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",
        "phoneNumber": "+447700900000"
    }
    ...
}

SAML 2.0 attributes​

SAML 2.0 service provider metadata document​

The example below shows a Service Provider (SP) metadata document to connect to SMS OTP and request the attributes: idpId, phoneNumber.

<?xml version="1.0" encoding="UTF-8"?><md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" ID="_45f42f65-39f9-4250-898e-f6297cb3f8ce" entityID="SAML Example SP">
    <md:SPSSODescriptor WantAssertionsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
        <md:KeyDescriptor use="signing">
            <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
                <ds:X509Data>
                    <ds:X509Certificate><SP_PUBLIC_SIGNING_CERTIFICATE_USED_FOR_SIGNING_REQUESTS></ds:X509Certificate>
                </ds:X509Data>
            </ds:KeyInfo>
        </md:KeyDescriptor>
        <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://*SP_CLIENT_DOMAIN*/saml/acs" index="1" isDefault="false"/>
        <md:AttributeConsumingService index="1" isDefault="false">
            <md:ServiceName xml:lang="en" xmlns:xml="http://www.w3.org/XML/1998/namespace">All attributes</md:ServiceName>
            <md:RequestedAttribute Name="idpId"/>
            <md:RequestedAttribute Name="phoneNumber"/>
        </md:AttributeConsumingService>
    </md:SPSSODescriptor>
</md:EntityDescriptor>

SAML 2.0 request example​

SAML 2.0 request example:

<samlp:AuthnRequest xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
                    AttributeConsumingServiceIndex="1"
                    Destination="https://*YOUR_SIGNICAT_DOMAIN*/auth/saml/login"
                    ID="d2d2ae0656604b739d9bf36edca452a7"
                    IssueInstant="2024-08-12T07:20:50.265Z"
                    ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
                    Version="2.0"
                    >
    <saml:Issuer xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">ENTITY_ID</saml:Issuer>
</samlp:AuthnRequest>

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:

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:Attribute Name="phoneNumber">
        <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>

UI language​

Default language

By default, the language property is set to English.

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

How to edit the language settings​

To edit the language displayed on the user interface (UI) of SMS OTP during an authentication session, you need to follow the syntax specific to each authentication protocol. Below, you can find examples for each case:

To change the language of the UI, you need to define the query string parameter ui_locales in your OIDC authorization request. For example, you can set the language to Greek (ui_locales=el) by passing the following in your request:

https://<SIGNICAT_ACCOUNT_DOMAIN>/auth/open/connect/authorize?
&client_id=OIDC_CLIENT_ID
&response_type=GRANT_TYPE_CODE
&redirect_uri=REDIRECT_URI
&ui_locales=el
&scope=OIDC_SCOPES
On this page