API references
Overview¶
MPass currently supports only one standard way of integration for SSO and SLO: SAML 2.0 via HTTP POST binding. Although MPass also supports HTTP Redirect binding, its usage is not recommended.
To completely understand how to integrate with MPass, please read [SAML Binding, 3.5].
The above reference describes how to correctly generate, encode and submit requests, as well as how to handle errors and responses.
MPass uses AuthnRequest/Response and LogoutRequest/LogoutResponse pairs to implement SSO and SLO.
For a detailed description of security related aspects, please read [SAML Security Considerations, 6.4].
SAML Structures¶
This section describes all the involved SAML structures in details.
Authn Request structure¶
An authentication request, referred to as AuthnRequest, is generated by Service and submitted to MPass via user's browser to direct him for authentication.
Here is an example of AuthnRequest generated by .NET sample:
<saml2p:AuthnRequest ID="_92a43de2-b6ab-460c-abe5-8580f828bf76" Version="2.0"
IssueInstant="2014-10-20T08:26:26.9933782Z"
Destination="https://mpass.staging.egov.md/login/saml"
AssertionConsumerServiceURL="http://localhost:50341/Account/Acs"
xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol"
xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
<saml2:Issuer>http://sample.testmpass.gov.md</saml2:Issuer>
<Signature xmlns="http://www.w3.org/2000/09/xmldsig#"><!-- ... --></Signature>
<saml2p:NameIDPolicy AllowCreate="true" />
</saml2p:AuthnRequest>
The following table describes structure attributes:
| Element or @Attribute | Type | Value | Description |
|---|---|---|---|
| @ID | any unique string | required | Generated by Service. This value will be returned back by MPass in Response/@InResponseTo attribute and can be checked in order to stop replay attacks. |
| @Version | Constant | 2.0 | This value is required and must be set to "2.0". |
| @Destination | URL | required | Must be set to MPass SSO URL. |
| @AssertionConsumerServiceURL | URL | optional, default value: set in Service settings | This URL is used by MPass to submit the SAML Response. |
| @ProtocolBinding (not present in above example) | URI | optional, default: urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST | URI reference that identifies the SAML protocol binding to be used when returning the Response. Although MPass supports HTTP POST and Redirect binding, Redirect binding is not recommended. |
| @ForceAuthn (not present in above example) | bool | optional, default: false | When set to "true", MPass will required the user to authenticate even if user already has a valid and authenticated MPass session. |
| @IsPassive (not present in above example) | bool | optional, default: false | When set to "true", MPass will not interact with the user and submit the SAML Response with current user authentication status. |
| Issuer | string | required | Represents the issuer of this AuthnRequest, usually as an URL. |
| Signature | Xml | required | Contains the signature of this AuthnRequest, applied using the private key of the Issuer. |
| NameIDPolicy | Xml | required | MPass currently ignore this policy element, but all Services are required to include it (exactly as in example above, including AllowCreate attribute) for compatibility. |
Response structure¶
MPass is generating a successful (i.e. user authenticated) or failed (i.e. user failed or cancelled the authentication) SAML Response in response to AuthnRequest. The Response is submitted to the Service via user's browser in the same way as the request. Before handling the response, Service must validate it accordingly.
Here is an example of successful SAML Response returned by MPass in response to the above AuthnRequest:
<samlp:Response ID="_7722d8dc-3401-4e16-b789-8c4db923ea86"
InResponseTo="_7b874d06-2b14-4dbe-b177-3a70140a5b66" Version="2.0"
IssueInstant="2014-10-20T08:39:48.786Z"
Destination="http://localhost:50341/Account/Acs"
Consent="urn:oasis:names:tc:SAML:2.0:consent:prior"
xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">
<saml:Issuer>http://devmpass.gov.md</saml:Issuer>
<Signature xmlns="http://www.w3.org/2000/09/xmldsig#"><!-- ... --></Signature>
<samlp:Status>
<samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success" />
</samlp:Status>
<saml:Assertion Version="2.0" ID="_b3ef6fcb-8db0-44dc-9a96-a3ca008ec55c"
IssueInstant="2014-10-20T08:39:48.786Z">
<saml:Issuer>http://devmpass.gov.md</saml:Issuer>
<saml:Subject>
<saml:NameID>admin</saml:NameID>
<saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
<saml:SubjectConfirmationData NotOnOrAfter="2014-10-20T08:49:48.786Z"
Recipient="http://localhost:50341/Account/Acs"
InResponseTo="_7b874d06-2b14-4dbe-b177-3a70140a5b66" />
</saml:SubjectConfirmation>
</saml:Subject>
<saml:Conditions NotOnOrAfter="2014-10-20T08:49:48.786Z">
<saml:AudienceRestriction>
<saml:Audience>http://sample.testmpass.gov.md</saml:Audience>
</saml:AudienceRestriction>
</saml:Conditions>
<saml:AuthnStatement AuthnInstant="2014-10-20T08:38:19.703Z"
SessionIndex="c5b3376a-a437-4b9c-addf-a3ca008e5883"
SessionNotOnOrAfter="2014-10-20T08:48:19.697Z">
<saml:SubjectLocality Address="127.0.0.1" />
<saml:AuthnContext>
<saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</saml:AuthnContextClassRef>
</saml:AuthnContext>
</saml:AuthnStatement>
<saml:AttributeStatement>
<saml:Attribute Name="FirstName">
<saml:AttributeValue>Admin</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="LastName">
<saml:AttributeValue>Adminovich</saml:AttributeValue>
</saml:Attribute>
</saml:AttributeStatement>
</saml:Assertion>
</samlp:Response>
The following table describes structure attributes:
| Element or @Attribute | Type | Value | Description |
|---|---|---|---|
| @ID | any unique string | required | Generated by MPass, provided for traceability purposes. |
| @InResponseTo | string | required | This value is set to the incoming AuthnRequest/@ID. Service can use it for traceability or check it to stop authentications by 3rd parties even with a stolen Service private key. |
| @Version | constant | 2.0 | This value is required and must be set to "2.0". |
| @IssueInstant | datetime | required, value in UTC | The instant of time when this Response was generated. To minimize the risk of replays, Service must not accept old responses. |
| @Destination | URL | required | The URL of the destination for this Response. Can be checked by Service to stop Responses aimed for a different Service or deployment environment. |
| @Consent | URI | optional | Additional information regarding user consent. Can be set to explicit (the consent was explicitly given during the authentication) or prior (the consent was persisted during previous authentication). |
| Issuer | string | required | Represents the issuer of this Response, which is obviously one of the MPass instances (dev, test or production environment). |
| Signature | xml | required | Contains the MPass signature of this Response, applied using MPass the private key. Service must verify this signature. |
| Status | xml | required | Contains Response status details. |
| Status/StatusCode/@Value | string | required | Specifies the top-level status of this Response. Possible values are Success (authentication succeeded), Requestor (failure on Service side), Responder (failure on MPass or user side) and VersionMismatch. See [SAML Core, 3.2.2.2]. |
| Status/StatusCode/StatusCode/@Value | string | optional | Second-level status code that specifies the reason of status. See [SAML Core, 3.2.2.2]. |
| Status/StatusMessage | string | optional | Additional human-readable message related to Response status. |
| Assertion | xml | included in successful Response | SAML Assertion that includes the details of the authentication, authentication conditions and authenticated identity. If required by Service, MPass can sign this similarly to the whole Response. |
| Assertion/@ID | any unique string | required | Specifies the ID of this Assertion. |
| Assertion/@IssueInstant | datetime | required, value in UTC | The instant of time when this Assertion was generated. |
| Assertion/Issuer | string | required | Represents the issuer of this Assertion, which is obviously one of the MPass instances (dev, test or production environment). |
| Assertion/Subject | xml | required | Contains details of authenticated identity (i.e. its subject) and authentication confirmation. |
| Assertion/Subject/NameID | string | required | Authenticated identity name identifier. This is usually the IDNP of the authenticated resident, but it can also be an unique username of MPass user. |
| Assertion/Subject/SubjectConfirmation/SubjectConfirmationData/@Recipient | URL | required | Specifies the expected recipient of this Assertion. Same as Response/@Destination. Required by SAML standard. |
| Assertion/Subject/SubjectConfirmation/SubjectConfirmationData/@InResponseTo | string | required | Same as Response/@InResponseTo. Required by SAML standard. |
| Assertion/Conditions | xml | required | Contains conditions under which this Assertion must be considered. |
| Assertion/Conditions/@NotOnOrAfter | datetime | required, value in UTC | Specifies the time until this Assertion can be considered as valid. |
| Assertion/Conditions/AudienceRestriction/Audience | string | required, could be many | Specifies the expected audience for this Assertion. Service must check for match with its AuthnRequest/Issuer. Note that an Assertion can have many audiences. |
| Assertion/AuthnStatement | xml | required | Contains authentication details. |
| Assertion/AuthnStatement/@AuthnInstant | datetime | required, value in UTC | Specifies the exact time instant of authentication. |
| Assertion/AuthnStatement/@SessionIndex | string | required | Specifies the ID of the MPass session under which the identity was authenticated. Must be used in LogoutRequest/SessionIndex to specify the exact session to log out from. |
| Assertion/AuthnStatement/@SessionNotOnOrAfter | datetime | required, value in UTC | Specifies the time until MPass session is valid. |
| Assertion/AuthnStatement/SubjectLocality/@Address | IP address | optional | Specifies the IP address of the client that performed the authentication as seen by MPass. |
| Assertion/AuthnStatement/AuthnContext/AuthnContextClassRef | string | optional | Specifies the instrument or method used for authentication. See [SAML Core, 2.7.2.2] and [SAML Authn Context, 3.4]. |
| Assertion/AttributeStatement | xml | required | Contains authoritative attribute values (i.e. claims) that represent the, are assigned or associated with authenticated identity. |
| Assertion/AttributeStatement/Attribute/@Name | string | required | The name of the provided attribute. |
| Assertion/AttributeStatement/Attribute/AttributeValue | string or xml | optional, could be many | Contains the value of the attribute. Note that some attributes can naturally have multiple values (e.g. identity Role in some Service). |
Logout Request structure¶
A LogoutRequest is generated either by a Service (as a result of user explicit request to logout) or MPass (in order to perform single logout, as a result of another service requesting user logout in the same authentication session or direct user logout in MPass UI).
Here is an example of LogoutRequest generated by .NET sample:
<saml2p:LogoutRequest ID="_bdeed8e2-5c79-4d5b-8f93-2620f1219753" Version="2.0"
IssueInstant="2014-10-20T08:51:44.8184811Z"
Destination="http://devmpass.gov.md/logout/saml"
xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol"
xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
<saml2:Issuer>http://sample.testmpass.gov.md</saml2:Issuer>
<Signature xmlns="http://www.w3.org/2000/09/xmldsig#"><!-- ... --></Signature>
<saml2:NameID>admin</saml2:NameID>
<saml2p:SessionIndex>ae94d066-67ba-4296-b149-a3ca0091b24e</saml2p:SessionIndex>
</saml2p:LogoutRequest>
The following table describes structure attributes:
| Element or @Attribute | Type | Value | Description |
|---|---|---|---|
| @ID | any unique string | required | Generated by MPass/Service, provided for traceability purposes. |
| @InResponseTo | string | required | This value is set to the incoming LogoutRequest/@ID. The requesting party can use it for traceability or check it to stop authentications by 3rd parties even with a stolen party's private key. |
| @Version | constant | 2.0 | This value is required and must be set to "2.0". |
| Issuer | string | Required | Represents the issuer of this LogoutResponse, usually as an URL. |
| Signature | xml | Required | Contains the signature of this LogoutRequest, applied using the private key of the Issuer. |
| NameID | string | Required | Contains the username (usually IDNP) of the logged in user, as previously returned by MPass in Response/Assertion/Subject/NameID. |
| SessionIndex | string | Required | Contains the ID of the session that was previously returned by MPass in Response/Assertion/AuthnStatement/@SessionIndex. |
Logout Response structure¶
A LogoutResponse is returned as a response to a LogoutRequest, either by MPass (in response to a Service request) or a service (as a response for single logout request from MPass).
Here is an example of successful LogoutResponse returned by MPass in response to the above LogoutRequest:
<samlp:LogoutResponse ID="_34650a27-f348-41cc-a2ef-e481d89a727c"
InResponseTo="_bdeed8e2-5c79-4d5b-8f93-2620f1219753" Version="2.0"
IssueInstant="2014-10-20T08:52:13.207Z"
Destination="http://localhost:50341/Account/AfterLogout"
xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">
<saml:Issuer>http://devmpass.gov.md</saml:Issuer>
<Signature xmlns="http://www.w3.org/2000/09/xmldsig#"><!-- ... --></Signature>
<samlp:Status>
<samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success" />
</samlp:Status>
</samlp:LogoutResponse>
The following table describes structure attributes:
| Element or @Attribute | Type | Value | Description |
|---|---|---|---|
| @ID | any unique string | required | Generated by MPass or Service. This value will/must be returned back by MPass/Service in LogoutResponse/@InResponseTo attribute and can be checked in order to stop replay attacks. |
| @Version | constant | 2.0 | This value is required and must be set to "2.0". |
| @IssueInstant | datetime | required, value in UTC | The instant of time when this LogoutResponse was generated. To minimize the risk of replays, requesting party must not accept old responses. |
| @Destination | URL | required | The URL of the destination for this LogoutResponse. Can be checked by requesting party to stop Responses aimed for a different party or deployment environment. |
| Issuer | string | required | Represents the issuer of this LogoutResponse, usually as an URL. |
| Signature | xml | required | Contains the signature of this LogoutResponse, applied using the private key of the Issuer. |
| Status | xml | required | Contains LogoutResponse status details. |
| Status/StatusCode/@Value | string | required | Specifies the top-level status of this LogoutResponse. Possible values are Success (logout succeeded), Requestor (failure on requesting side), Responder (failure on responder side) and VersionMismatch. See [SAML Core, 3.2.2.2]. |
| Status/StatusCode/StatusCode/@Value | string | optional | Second-level status code that specifies the reason of status. See [SAML Core, 3.2.2.2]. |
| Status/StatusMessage | string | optional | Additional human-readable message related to LogoutResponse status. |