Connect with SAML
Connect with SAML
Overview
The SAML onboarding process begins enabling SAML functionality on an existing Checkbook customer’s account. In order for this to happen, the Checkbook customer (i.e. the identify provider) must provide Checkbook (i.e. the service provider) with:
-
An x509 public key certificate that will be used by Checkbook to verify the signature of the SAML assertions.
-
A URL for the identity provider’s single sign-on service. This is used by Checkbook for redirection once a Checkbook session has expired to improve the user experience; otherwise, the user will be redirected back to the Checkbook login page, which leads to a poor user experience.
-
(optional) A URL for the identity provider’s single logout service. If a user selects ‘logout’ via the Checkbook dashboard, the identity provider can also choose to logout the user’s sessions with other service providers as well.
SAML can have 2 sign-in flows: service-provider initiated and identity-provider initiated.
Service-provider initiated
Service-provider initiated flows would allow users to “Login with X” to their Checkbook account. This is similar to the “Login with Google” functionality that may be seen on other websites. Checkbook does not currently offer service-provider initiated SAML
Identity-provider initiated
With identity-provider initiated flows, a user first logs in to their identity provider. From their identity provider, they can then click on a button or link that is implemented by the identity provider that will automatically provision (if the user does not exist on the Checkbook platform) and login the user to the Checkbook dashboard:
- The user logs into their account with their IdP, where they would be presented with a button to take them to their Checkbook dashboard (similar to below). This functionality is implemented by the identity provider (i.e. Okta):
-
When the user clicks the button to take them to the Checkbook dashboard, this would initiate a HTTP
POST
request from the user’s browser to Checkbook’s SAML assertion consumer service (e.g. http://checkbook.io/web/v1/auth/saml/?acs). The body of the request would include the SAML assertion as a base64 encoded value for the “SAMLResponse” key in a application/x-www-form-urlencodedPOST
request -
If the authentication is successful, the user will be directed to the user branded Checkbook dashboard
<?xml version="1.0"?>
<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
ID="checkbook8e8dc5f69a98cc4c1ff3427e5ce34606fd672f91e6" Version="2.0"
IssueInstant="2014-07-17T01:01:48Z"
Destination="https://app.checkbook.io/web/v1/auth/saml"
InResponseTo="CHECKBOOK_4fee3b046395c4e751011e97f8900b5273d56685">
<saml:Issuer>http://example.com/metadata</saml:Issuer>
<samlp:Status>
<samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
</samlp:Status>
<saml:Assertion xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
ID="pfxa63aa511-d0c1-e208-bbaa-146a610c8ef9" Version="2.0"
IssueInstant="2014-07-17T01:01:48Z">
<saml:Issuer>http://example.com/metadata</saml: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/2000/09/xmldsig#rsa-sha1"/>
<ds:Reference URI="#pfxa63aa511-d0c1-e208-bbaa-146a610c8ef9">
<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#"/>
</ds:Transforms>
<ds:DigestMethod
Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
<ds:DigestValue>YmMSh0NoFwQ+Af9F7b8UEjbjQVk=</ds:DigestValue>
</ds:Reference>
</ds:SignedInfo>
<ds:SignatureValue>cCdGbH2ySv4G9Z6ir/F/Mj8Geh58usxH7DkOWrOCu08qFNZ98dPMwnmnOZQSlaT8
uQtKoAYZ9YoGdB1b3UevEGkl9ufy7pRvvHe0bkJrpb6GKU4165Yx51HGH5EWtwR6
n8bwZvE3qsI5FTf90vL2uKFnwCXJLOFWLln/cHWE0sQ1NIruHfavwuOKztGeASlz
+izY9n31e0sPbd19GPCkONxnBuMpH73/DZxSvsHEfLe6GyRRk5T5dFzGIcr9wYMH
f0stO5tSJyYV8oSJ2rW1/TVK5Hx2OP1Q5l7nbRhx3ZOt4Cbut9Lm68h+EjU0hYzf
06MPcCfOe80yRFTr/rlNJw==</ds:SignatureValue>
<ds:KeyInfo>
<ds:X509Data>
<ds:X509Certificate>MIIDazCCAlOgAwIBAgIURf/jKIkgx5EtyNvV9GIQ8yUefQMwDQYJKoZIhvcNAQEL
BQAwRTELMAkGA1UEBhMCQVUxEzARBgNVBAgMClNvbWUtU3RhdGUxITAfBgNVBAoM
GEludGVybmV0IFdpZGdpdHMgUHR5IEx0ZDAeFw0yMTA3MDgyMDU5MTFaFw0zMTA3
MDYyMDU5MTFaMEUxCzAJBgNVBAYTAkFVMRMwEQYDVQQIDApTb21lLVN0YXRlMSEw
HwYDVQQKDBhJbnRlcm5ldCBXaWRnaXRzIFB0eSBMdGQwggEiMA0GCSqGSIb3DQEB
AQUAA4IBDwAwggEKAoIBAQDPgyXwGAXddwJqRMaYqbAmEMB3OzPIGSpvTdCMIorg
fiiZqLxtS/GprPqx+EEHW+DwCPNUe1ib5qqIzdYWsoxw6SBNJJAR5fiUUdiPCGL9
xHpRXJTwbvLKAD+xQJkaiN1UijK8s5OQl4Tw7Q7AJf01WZJ9b+it2/CF4ESB1Pbu
oOtkzHINxeUyz1uAzLrBH0jDYS93ji5HGodKkjcKJ5knnL1VNbg7PYbnSVDyK5fS
Hx+PaEtlGfapaGulnYxwPZxAcFnCmmUt1wdxrFVR0mSkMlS7m8+RWk01sxL1em3Z
3aURQHL63n5Buki/2K9e+9P5IEta5WtGOZpTLekmq2U1AgMBAAGjUzBRMB0GA1Ud
DgQWBBS4lJ1b7py7ReUSG3nQN3/eFAJJIDAfBgNVHSMEGDAWgBS4lJ1b7py7ReUS
G3nQN3/eFAJJIDAPBgNVHRMBAf8EBTADAQH/MA0GCSqGSIb3DQEBCwUAA4IBAQBI
C841EpZlPJNvOEihbSKCB3+kTHQMcwT+3GNXWbBnEsn0bwicZTdwlmLtItQbMrG8
WFrUxTuD1Paq2t6kMsjD6zsXJYH/DU7QK/RFen2deuec+BZtS6ZmqlQHbBwKf/EG
1OQW9HD2tp5SvCONc0EHG4y6ZdgE+Kpf1v1esZOCaMa+kNvrB4S2UkErK1bqplfU
/n5TQxstsnqCaJc80sp6CVEhvTldPEVYEMsBxNNTiL4GrNF0HVHaw21Y78Nzvom1
cPDeDXQP4Bqm9Y2if/qz9hg2JngRClbTNdvq2vVnWl283iNCjuL94eFlqq97TwGk
MqhYmN40KEtFU4SvkAWn</ds:X509Certificate>
</ds:X509Data>
</ds:KeyInfo>
</ds:Signature>
<saml:Subject>
<saml:NameID
Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">[email protected]</
saml:NameID>
<saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
<saml:SubjectConfirmationData NotOnOrAfter="2024-01-18T06:21:48Z"
Recipient="https://app.checkbook.io/web/v1/auth/saml"
InResponseTo="CHECKBOOK_4fee3b046395c4e751011e97f8900b5273d56685"/>
</saml:SubjectConfirmation>
</saml:Subject>
<saml:Conditions NotBefore="2014-07-17T01:01:18Z"
NotOnOrAfter="2024-01-18T06:21:48Z">
<saml:AudienceRestriction>
<saml:Audience>https://app.checkbook.io/web/v1/auth/saml/metadata</saml:Audience>
</saml:AudienceRestriction>
</saml:Conditions>
<saml:AuthnStatement AuthnInstant="2014-07-17T01:01:48Z"
SessionNotOnOrAfter="2024-07-17T09:01:48Z"
SessionIndex="_be9967abd904ddcae3c0eb4189adbe3f71e327cf93">
<saml:AuthnContext>
<saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:Password</saml:Authn
ContextClassRef>
</saml:AuthnContext>
</saml:AuthnStatement>
<saml:AttributeStatement>
<saml:Attribute Name="first_name"
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
<saml:AttributeValue xsi:type="xs:string">John</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="last_name"
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
<saml:AttributeValue xsi:type="xs:string">Smith</saml:AttributeValue>
</saml:Attribute>
</saml:AttributeStatement>
</saml:Assertion>
</samlp:Response>
A few things to note about this SAML assertion:
-
The saml:NameID attribute contains the email address of the user who will be logged in to the Checkbook dashboard.
-
The ‘saml:Attribute Name="first_name"’ and ‘saml:Attribute Name="last_name"’ attributes contain the first and last name of the user who is logging in.
-
The ds:X509Certificate contains the x509 public key associated with the private key that was used to sign the request.
-
ds:SignatureValue contains the signature for the SAML assertion.
API Access
The identity-provider initiated SAML overview referenced above gives an identity provider the ability to login a user to the Checkbook dashboard. But what if the identity provider also wanted the ability to interact with the Checkbook platform on behalf of this user via the API?
The identity provider can use Checkbook’s OAuth token endpoint,
https://app.checkbook.io/web/v1/auth/oauth/token, to generate an OAuth token. This is similar to generating a bearer token in the standard OAuth flow:
https://docs.checkbook.io/docs/bearer-token
A few things to note:
-
The grant type used is “urn:ietf:params:oauth:grant-type:saml2-bearer” instead of “authorization_code”.
-
Instead of providing the authorization code in the “code” parameter, the SAML assertion is provided in the “assertion” parameter, base64 encoded and without the padding characters (i.e. ‘=’). More information about this implementation can be found in RFC7522: https://datatracker.ietf.org/doc/html/rfc7522.
Updated 11 months ago