Clio Identity is Clio's authentication service and identity provider. Similar to how you may see a "Login with GitHub" or "Login with Google" button when authenticating with an application on the web, third-party developers can leverage Clio Identity as an identity provider, cutting the time needed to write and maintain an authentication system for an application and streamlining account management for users.
Integrating your application with Clio Identity allows your application to utilize Clio’s single sign-on (SSO) services, making it easy for Clio users to securely sign in and access your application at the click of a button. Additionally, it enables you to launch your app in the new App Integrations experience within Clio Manage.
Clio Identity uses OpenID Connect (OIDC) as its identity layer on top of the OAuth 2.0 protocol. For additional information, please refer to the OIDC documentation.
*Note that user accounts may not be able to use single sign-on immediately; it only becomes available a few hours after user creation.
For your convenience, we have a GitHub repository with a sample implementation demonstrating how to integrate with Clio Identity and allow Clio users to SSO into an application. Any developers that would like to see this example will need to send us their GitHub account handles so that access can be granted. The application is built using Ruby on Rails, but the general workflow is extendable to your framework of choice.
Obtaining Clio Identity Keys
In order to register your application on the Clio Identity service, we need to know a list of redirect URIs you will be using for your authorization flow, in addition to several other required pieces of information outlined in our article on launching your app in the App Integrations experience. The list of redirect URIs should include both your development and production redirect URIs, if applicable.
Once we receive your redirect URIs, we will get back to you with your Clio Identity App Key and App Secret. Please reach out to us at firstname.lastname@example.org if you have not received your keys.
To log in, a user starts by making a request to the Clio Identity API by asking for authorization using the following parameters:
|Response type returned after authorization|
|Your Clio Identity App Key|
|Callback URL to redirect to after authorization|
|Scopes you’re requesting to access (usually "openid")|
|A nonce you provide that will be returned to you in the callback, so you can validate the callback came from a request you made|
This is most commonly done using a “Sign in Clio” button or link on your application’s log in page, which makes the following request:
Upon visiting the Clio My Account URL above, the user will be asked to sign in to their Clio account and permission will be requested to allow your application to access their Clio Identity information.
A user authorizing Clio Identity scopes for an application.
Once the user allows your application to access their Clio account, your grant will be approved and the user will be redirected to the redirect URI provided in the URL parameters of the previous step.
We recommend redirecting your users to the Clio Manage authorization process outlined in the Clio Manage API Documentation. As a result, your application will now have access to both the user’s Clio Identity and Clio Manage information.
If the user grants your application access, your application can now fetch Clio Identity-related information from the user’s account. Your application should now perform a request to receive the Clio Identity id_token and access_token:
The response will contain an id_token, which is a JSON web token (JWT) containing the user’s Clio Identity data, such as their first_name, last_name, and email. Additionally, a sub will be provided, which is a unique identifier for the OIDC subject, along with the iss, which is the URL of the issuer (in this case, it would be the URL of Clio My Account). Note that you can not pass the client_id and client_secret parameters as part of the request header, and they must be included in the request body.
In the case that authentication fails (for example when the user is not yet able to use Single Sign-On), the following request parameters will be returned:
User Denied Access to Clio Identity
In the case that user cancels the request for your application to their Clio account, the following request parameters will be returned:
Safety and Response Validation
As an OIDC/OAuth Client, your application must validate the responses it gets back from our Clio Identity Server, to make sure no attacker is imitating the Clio Servers or tampering with the information in any way.
We adhere to OAuth 2.0 and Open ID standards for our authorization and authentication processes. The respective RFCs are linked below for the interested reader. Note that validation steps marked as “MUST”s are considered mandatory for eligibility to appear on Clio’s App Store, and we highly recommend covering as many validation steps marked as “SHOULD”s as possible.
Token Response Validation
Since OIDC is built on top of OAuth, the response object contains information pertaining to both standards, as a result the validation can be done in multiple layers:
- You must validate the OAuth portion of the response. This includes validating the presence of access_token, token_type, refresh_token, and expires_in parameters. Follow the steps in RFC 6749 (OAuth), especially those in Sections 5.1 and 10.12.
- Validating the ID token can be done in two steps: first, decode the ID Token using the appropriate keys and algorithm. Then validate the structure of the token and the claim values. Follow the ID Token validation rules in Section 18.104.22.168 of the Open ID specs.
- Clio Identity uses the “RS256” algorithm.
- Public keys can be found at https://account.clio.com/.well-known/jwks.json.
- Follow the Access Token validation rules in Section 22.214.171.124 of the Open ID specs (Optional).
An example of token validation using Ruby on Rails can be found in our Sample Code repository.
Creating a 'Sign in with Clio' button
We highly encourage you to include a 'Sign in with Clio' button on your application's login screen to promote your new Clio single sign-on functionality to your users. To ensure the button meets Clio's accessibility and brand guidelines and to allow customers to have a consistent experience across all services using single sign-on with Clio, we have provided a styling guideline including downloadable assets for reference.