Third-Party App/Website Authorization
This documentation is intended for developers wishing to use token authorization with Connections Online instead of needing user passwords.
Introduction
It is now possible to connect a 3rd-party application or website (called an "app" from now on) to Connections Online. This allows an app to use the API interface as a Connections Online user without knowing the user's password. Here is the process by which client authorization works:
- Register the app with Connections Online to receive an App Token and Secret Key.
- Pass an encoded JSON token from the app to Connections Online to request a user or site token.
- Receive back an encoded JSON token that contains the user or site authorization token.
Register the Application with Connections Online
The first step in connecting an app to Connections Online is to request an AppToken and AppSecret. The AppToken is used by Connections Online to identify which app is requesting authentication. The AppSecret is used as an encryption key to encode the request and response JSON packets between the app and Connections Online.
- Visit https://col.connectionsonline.net/developer. You must have a valid Connections Online account to create an app.
- Click the Add button to create a new application.
- Enter the details in the New Application window.
- Application Name - this is the name that will display for the token in the Developer App list and also when the user is prompted for Authorization acceptance by Connections Online.
- Return URL - this is the URL to which Connections Online should return the authorization packet.
- Privacy URL - Optional. A privacy agreement can be shown to the user when they authorize the application to login to Connections Online.
- Icon - Optional. This is an icon to be shown to the user when they authorize the application to login to Connections Online.
3. Click Insert to complete the registration. The AppToken and AppSecret will be displayed. The AppToken can be retrieved from the list any time after creation. However, the AppSecret will only be shown this one time, so please save it and keep it private. It cannot be recovered.
Requesting Authorization for a 3rd Party Application or Website
Now that the app is registered with Connections Online, the AppToken and AppSecret can be used to request authorization from Connections Online. There are two types of authorization tokens available: Site and User.
- Site - Site tokens can be used for any user for the site. Site tokens can only be authorized by Site Administrators. They can then be passed to Connections Online with any user to log in.
- User - User tokens are specific to one user. The request must be authorized by the same user.
To make the request to Connections Online, you must send the appropriate query string parameters to the Connections Online authorization URL: https://col.connectionsonline.net/auth/. Those parameters are AppToken, the AppToken you received from registering the application, and Type, which indicates you want a Site token (Type=1) or a User Token (Type=44). The default Type is User if you leave the Type parameter off of the request.
For example, using the Sample CU Application, a Site token request would be made to https://col.connectionsonline.net/auth/?apptoken={AppToken}f1c5d90e-7da3-46d8-bad5-1d2982a2339a&type=1. For a user token, remove the "&type=1" or change it to "&type=44".
User Authorization of Request
When Connections Online receives the request, a screen will display asking the user to authorize the application's request for a token. The example below is for the "Sample CU Application". Notice that if a Privacy URL is entered during application registration, a "View Privacy Policy" link will show to the user. If none is entered, the link will not appear. The icon will also not appear if not uploaded during registration.
Two actions can happen here: the user clicks "Allow" to grant access, or the user clicks "Cancel" to deny access. Both actions return to the application with different data as explained in the next section.
Receiving Authorization (or Not)
If the user authorizes the 3rd party to app to connect to Connections Online, it will return to the Return URL, specified in registration, with the authorization packet. The packet is in the form of a JSON web token and is encoded with the app's SecretKey. The packet content is slight different depending on the type of token (Site or User).
Site Token
- iat - a timestamp of when the packet was created.
- jti - a GUID identifying the packet.
- token - the COL authorization token prefixed with "{SiteToken}".
- desc - the Site name
- siteid - the GUID for the Site used by Connections Online.
- username - the username for the authorizing user.
- userid - the GUID for the User used by Connections Online.
User Token
- iat - a timestamp of when the packet was created.
- jti - a GUID identifying the packet.
- token - the COL authorization token prefixed with "{UserToken}".
- desc - the user's full name.
- username - the username for the authorizing user.
- userid - the GUID for the User used by Connections Online.
The token is returned in the jwt= query string parameter of the Return URL. For the Sample CU Application example, the return URL would be http://www.samplecu.org/col?jwt=<packet>.
If there is an error, the packet returned will include iat, jti, and an error field.
If the user cancelled the authorization by clicking "Cancel" on the request window, the Return URL will include "cancel=1", such as http://www.samplecu.org/col?cancel=1.
As mentioned, the JSON web token is encoded on send using the app's SecretKey. It will need to be decoded upon receipt using the same SecretKey. There are libraries available to do this decoding. Below is a code snippet from C# showing the decoding of the packet using the JWT assembly.
string jwt = Request.QueryString["jwt"];
string result = JWT.JsonWebToken.Decode(jwt, "{SecretKey}5983338e-e6b4-4bcf-aff6-0a7d5791e5e6", false);
Using the Authorization Token
Once you receive the Site or User Token from Connections Online, you can then use the token to access the API. To do this, pass the username and token in the Request Header Authorization field. Note that the token must include the {SiteToken} or {UserToken} prefix. The format for the Authorization field is Basic + Base64 encoded Username:Token. Below is a simple code snippet illustrating the Authorization for a User Token for js@samplecu.org.
Request.Headers["Authorization"] = "Basic " + Base64.Encode("js@samplecu.org:{UserToken}38B98C44-542C-4D00-903F-A5FD95E2C0B2")
For more information and examples on using the Token to access the API, please visit Getting Started in the API Documentation.
Please sign in to leave a comment.
Comments
0 comments