Skip to main content

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.

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:

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=el to set the SMS OTP UI to Greek.

Default language

By default, the UI language is English.

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

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

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": "el" to set the SMS OTP UI to Greek.

Default language

By default, the UI language is English.

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

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

Set the UI language

To change the language on the Email OTP UI, you need to specify the language by using the signicat:param:language parameter in the SAML AuthnRequest Extensions. For example, to set the Email OTP UI to Greek (el), do this:

<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:language"
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">el</saml2:AttributeValue>
</md:RequestedAttribute>
</req-attr:RequestedAttributes>
</saml2p:Extensions>
Default language

By default, the UI language is English.

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

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