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:

Alt text

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

Alt text

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-urlencoded POST 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.