Purpose: This document covers the process to make an OAuth connection to the Orion API for an Orion user. To log in to the API as a partner API user, using Basic authentication to get access and refresh tokens, see the Guide under Authorization titled Basic Authentication.
Simple Use Case: Firm has build multiple workflows within their platform and wants to call the Orion API to pull in details real-time or to make updates as the user interacts with them. They the user to enter their Orion credentials once, but be able to call the API as needed day to day.
OAuth can be used for SSO initiatives and is recommended for consumption of the API in most cases, especially anything beyond a simple occasional change.
Scope and outputs: OAuth is the recommended authentication method for SSO purposes or for regular changes and complex work via the API.
Process Overview:
- Obtain Partner ID and Secret from Orion.
- Provide Orion URLs that will be used for redirect if applicable.
- Call OAuth endpoint with id and secret to obtain token.
- Get Access and Refresh Token
Process Steps
- Obtain a partner id, and partner secret – Contact the Orion Support SME Integrations team or your Orion representative to obtain these values. They are used to identify the partner who is logging in as a user.
· Client_id: <integer value>
· Client_secret: <guid>
- Determine the URLs Orion should redirect to during the OAuth process
In the OAuth process you will call an authorization endpoint and must specify a redirect_url parameter, specifying where the Orion API should redirect to, with the results of the authorization endpoint.
Each URL you may use as a redirect_url must be added to our whitelist for the OAuth process to succeed. You can have more than one redirect_url – for instance, one for development, one for staging, and one for test. You can have one list for test and one for production, or use one list for both environments.
Only the URLs, not including the query parameters, must be added to a whitelist for the OAuth process to succeed. In order to get the URLs added to the whitelist, please send the list to the Orion Support SME Integrations team or your Orion representative.
NOTE: You will also get an error message if the redirect_uri is not a URL in the whitelist. Also note that you may see this message if you do not enter the correct client_id; this is because the whitelist is tied to your client_id.
- Call The Orion OAuth endpoint to obtain a code to allow your application to get a token.
To interact with the Orion API and the OAuth endpoints you will use the main URL for the Orion environment:
· Stage: https://stagingapi.orionadvisor.com/api
· Production: https://api.orionadvisor.com/api
Note: Throughout the remainder of this article, we will show only the relative URLs; just remember to include the base URL for the environment you’re using.
To start the OAuth process for a user login call this endpoint:
POST /oauth/?response_type=code&redirect_uri={uri}&client_id={id}&state={state}
OAuth Endpoint Parameters
- response_type – this must always equal code.
- redirect_uri – Replace {uri} with the redirect URI
o This URI must point to an endpoint in your application that can take the temporary code and use it to get tokens in the second call to the API.
o All possible redirect URIs must be given to us ahead of time, so we can whitelist them.
- client_id – Replace {id} with your client_id.
- state – Replace {state} with any value you want to use in the process. It will be posted back unchanged to your redirect_url if you need to maintain some state such as a page the user is currently on.
Returns a 401 Unauthorized Response
Verify these things:
- The spelling of the parameter names match the example above,
- None of the parameters in the example is missing or empty, and the redirect_uri parameter value is UrlEncoded.
Connecting with an API user account instead of an Orion user account
Note that the first OAuth endpoint is only used to log in as an Orion user, which will connect in the user’s context. If you are logging in with an API user account, you do not need to do this step.
4. Get the Access Refresh Tokens
Finally, Orion has three ways to retrieve an access token with authorization code to the Orion API Security/Token endpoint. This will authorize your application to access the user’s data through the API. The API will return a valid access_token and refresh_token. For example:
POST w/ Parameters –
curl –location –request POST ‘https://api.orionadvisor.com/api/v1/Security/Token?grant_type=authorization_code&code={authorization_code}&client_id={client_id}&redirect_uri={redirect_uri}&response_type=code&client_secret={client_secret} ‘
POST w/ Headers –
curl –location –request POST ‘https://api.orionadvisor.com/api/v1/Security/Token ‘
–header ‘grant_type: authorization_code’
–header ‘code: {authorization_code}’
–header ‘client_id: {client_id}’
–header ‘redirect_uri: {redirect_uri}’
–header ‘response_type: code’
–header ‘client_secret: {client_secret}’
POST w/ Body –
curl –location –request POST ‘https://api.orionadvisor.com/api/v1/Security/Token ‘
–header ‘Content-Type: application/x-www-form-urlencoded’
–data-urlencode ‘grant_type=authorization_code’
–data-urlencode ‘code={authorization_code}’
–data-urlencode ‘client_id={client_id}’
–data-urlencode ‘redirect_uri={redirect_uri}’
–data-urlencode ‘response_type=code’
–data-urlencode ‘client_secret={client_secret}’
NOTE:
- The grant_type query parameter must be authorization_code
- The code query parameter must be the {authorization_code} value returned when Orion redirected to the redirect_url you specified.
Example JSON response:
{
“access_token”: “”,
“expires_in”: 36000.0,
“refresh_token”: “”
}
access_token : will be used to call Orion Connect endpoints, till it’s lifespan expires. (default 10 hrs)
Expires_In : shows how long the lifespan of the access token is set to in seconds.
refresh_token : one time use token that is used to obtain a new access token and refresh token. Lifespan of refresh token is 375 days. This value can be changed as requested.
If you do not get a access token, there are a few possible causes:
- The authorization code has a lifetime of one minute, so it could have timed out and expired.
- The access token lifetime may not have been set; the integration team can verify that it is set correctly.
- If you are using a third-party tool to connect to Orion, such as curl, or Postman, or a plug-in to another application like Sql Server Integration Tools (SSIS), check to see if that tool requires custom settings to handle a REST call to our OAuth 2 endpoints.
Token Endpoint Returns a 401 Unauthorized Response
Verify these things:
- The values shown above in the Security/Token URL are part of the URL, and not in the headers and/or body of the request. The API looks for the parameters and their values in the URL itself for this particular endpoint.
- The spelling of the parameter names match the example above
- None of the parameters in the example is missing or empty, and the redirect_uri parameter value is UrlEncoded.
Refresh Token usage
a refresh token call can happen one of three ways:
curl –location –request GET ‘https://api.orionadvisor.com/api/v1/Security/Token ‘
–header ‘Authorization: Bearer {refresh_token}’
–header ‘Accept: application/json’
–header ‘client_id: {client_id}’
–header ‘client_secret: {client_secret}’
curl –location –request POST ‘https://api.orionadvisor.com/api/v1/Security/Token ‘
–header ‘Content-Type: application/x-www-form-urlencoded’
–data-urlencode ‘Authorization=Bearer {refresh_token}’
–data-urlencode ‘Accept=application/json’
–data-urlencode ‘client_id={client_id}’
–data-urlencode ‘client_secret={client_secret}’
curl –location –request POST ‘https://api.orionadvisor.com/api/v1/Security/Token ‘
–header ‘Authorization: Bearer {refresh_token}’
–header ‘Accept: application/json’
–header ‘client_id: {client_id}’
–header ‘client_secret: {client_secret}’
Example JSON response:
{
“access_token”: “”,
“expires_in”: 36000.0,
“refresh_token”: “”
}
Tip:
- Refresh token is specific to a user and client id.
- a user will only have one refresh token active per client id.
- a refresh token is voided, once a refresh token is used or a new one is assigned to a user for that client id.
Process Tips or Controls:
- Including the API Version in the URL
You should NOT use api/v1/oauth in the URL; just use /api/oauth/. If you add the version number in the URL, the browser will show its native login dialog instead of navigating to the OAuth login page.
Not URL-Encoding the Redirect URI parameter
You should URL Encode your redirect_uri value to avoid confusion when either the browser or the server tries to read and use the URL. If you don’t, the OAuth page may show an error message stating “Could not create authentication code.” You may also get an error message about a missing or invalid redirect_uri parameter.
2. Missing Query Parameters
If you are missing the client_id, response_type, or redirect_uri parameters, you will get an error message in the OAuth page reminding you that any missing values are required.
3. Using a Redirect URL That is Not Whitelisted
You will also get an error message if the redirect_uri is not a URL in the whitelist. Also note that you may see this message if you do not enter the correct client_id; this is because the whitelist is tied to your client_id.
4. The OAuth URL launches our OAuth login page
If the user hasn’t done so before, the OAuth system will require the user to allow the Orion Web API to share their data with your application. The user should sign in with their Orion user name and password.
Remember that you should not use your integration API user account for the firm; API user accounts are not allowed to log in through this page.
When the user clicks the Sign In button, they will be signed in and see a page asking them to Allow your application access to their Orion data. Once this step is completed, you will be able to use tokens to authenticate in the future without user interaction.
5. Handle the Redirection to your URL
Once the user grants your application access permission, a temporary_token will be passed to the redirect_uri you provided. For example:https://yoursite.com/oauth/redirect?code={temporary_token}&state={value_you_sent_to_us}