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