Classy Login (Pre-release)

Classy's Single Sign On service is a convenient way for people to register and log into your app using their Classy account. Classy's Single Sign On implementation complies with OpenID Connect.

This document describes Classy's implementation of OpenID Connect and the tools made available to 3rd party developers to help them use Classy as an OpenID Identity Provider.

Note for "power developers"

If you are already familiar with OpenID Connect protocol, here is all you need to know to configure Classy as an Identity Provider:

https://login.classy.org/authorize

https://api.classy.org/oauth2/auth

https://api.classy.org/2.0/me

Single Sign On flow - Overview

During this flow:

1. The user that needs to be authenticated is sent to https://login.classy.org/authorize?client_id={your_app_ID} (aka the "Authorization endpoint"),
2. The user authenticates, an authorization code is generated and passed to your application,
3. Your application exchanges the authorization code with an access token that can be used to retrieve the user identity.

There are several ways to send the user to the authorization endpoint and to retrieve the authorization code:

1. The "redirect method" during which the user is redirected to the authorization endpoint and redirected back to your application,
2. The "popup" and the "iframe" methods during which the user never leaves your application. These methods require the use of our javascript SDK.

The way the authorization code is passed back to your app depends on the method ("redirect", "popup" or "iframe") being used.

Implementing the flow, step by step

Step One - Send the user to the Authorization endpoint

Using the redirect method

When your application needs to authenticate a user, this user shall be redirected to the authorization endpoint. The authorization endpoint URL is of the form:

        https://login.classy.org/authorize
                    ?client_id=xxx
                    &response_type=code
                    &state=xxx
                    &redirect_uri=xxx
                    &scope=xxx
    

Where:

Using the popup method

You first need to include the javascript SDK in your page.

Then, just bind the classy-login-btn class to an html element. The single-sign-on popup will be thrown when the user clicks this element. You must also define the function that will handle the authorization code once the user has authorized your application ("authHandler" in our example).

Where:

Alternatively, you can also use the Classy.login() method provided by the SDK:

Using the iframe method

You first need to include the javascript SDK in your page.

Include a container for the iframe in your page with the classy-login-iframe class.

Where:

Step 2 - Retrieve the authorization code

Once the user authorized your app on login.classy.org, an authorization code is generated. The way the authorization code is communicated to your application depends on the SSO method chosen.

Using the redirect method

Once the user authorized your app, he will be redirected to:

<redirect_uri>?code=xxx&state=xxx

Where:

Using the popup or iframe methods

The authorization code will be passed to the callback method bound to the html element ("authHandler" in our example). This method shall pass this authorization code to your backend server.

Step 3 - Exchange the authorization code with a member access token

Once your backend is in possession of the authorization code, it can be exchanged with an access token:

An access token will be returned:

Step 4 - Retrieve the user identity

You can now retrieve the user identity by requesting the GET /2.0/me endpoint using the access token.

which will return a response containing the following data:

Javascript SDK

Classy is providing a javascript SDK to help you implement the "popup" and the "iframe" methods of the SSO flow.

Installing the SDK

Just include the following lines in your pages, just before the </body> tag of your html document:

SDK Reference

The SDK is asynchronously loaded so that it doesn't block loading other elements of your page. As a result, you must wait for the SDK to be loaded and initialized before using any of its methods:

Classy.login(options, callback)

This method will launch a popup asking a user to authenticate on Classy and authorize (if not already done) your app for the requested scope. The callback function is called with the authorization result.

Classy.status(callback)

This method will provide information regarding the login status of the user on login.classy.org.

Classy.logout(callback)

This method logs the user out of login.classy.org.

Classy.parseDOM()

If HTML elements having the classy-login-btn or the classy-login-iframe class were added to the document after the SDK was initialized, they won't be taken into account by the SDK.

This method will let the SDK re-parse the document.

Authorization Scope

When sending the user to the authorization endpoint, you must define the "scope" of the authorization your app is requesting. A scope is a set of permissions your app is asking a user to grant. It will affect the consent screen the user will see on login.classy.org.

Here is the list of the scope currently made available: