OAuth 2 Documentation

RWTH Aachen information service APIs use the Auth 2.0 protocol for authentication and authorization. Different OAuth 2.0 workflows are supported respecting capabilities and limits of common application szenarios.

Basic Steps

When using OAuth 2.0 you will always follow these basic steps to authorize your application to access RWTH Aachen information services:

  1. Register application
  2. Obtain an access token from the OAuth 2 Server
  3. Access RWTH Aachen information service APIs using the access token
  4. Refresh the access token

Please have a look at the different workflows for an example on how to gain authorization to RWTH Achen information services using OAuth 2.

App Guidelines

When developing an app using the OAuth 2.0 and other information services of RWTH Aachen University please review the app guidelines here (currently in german language only).

Device Workflow

The user will first interact with application on the device, obtain an URL and a code from the device, then switch to a browser and navigate to the URL specified in the application, authenticate, and enter the code. The application and the browser do not have to run on the same device (e.g. the application runs on a mobile phone whereas the browser runs on a computer).

The application starts the workflow by making a request to a URL for a new code. The response contains the needed information, such as the URL and code that should be shown to the user. The application shows these values to the user, and begins polling a URL. The response to a message in this polling sequence indicates whether or not the user has approved access. After the user approves access (via another computer or device), the response contains an access and refresh token.

After the application has received the access and refresh tokens, it may store the refresh token for future use, and use the access token to access an information service. Once the access token expires (after 30 minutes), the application obtains a new one with the refresh token (see Using a Refresh Token).

Obtaining a User Code

You will first need to register your application here. To proceed with this flow, you will need the client_id created during application registration, and you will need to embed them in your application.

After you have the client_id, you send an HTTP POST to the OAuth 2.0 endpoint at https://oauth.campus.rwth-aachen.de/oauth2waitress/oauth2.svc/code with your client_id and a list of scopes. The following is an example request for a user code:

POST /oauth2waitress/oauth2.svc/code HTTP/1.1
Host: oauth.campus.rwth-aachen.de
Content-Type: application/x-www-form-urlencoded

client_id=QhV1IXlzticl9JCKgH01bhOMlu.app.rwth-aachen.de&
scope=l2p.rwth userinfo.rwth

or in CURL:

curl -d "client_id=QhV1IXlzticl9JCKgH01bhOMlu.app.rwth-aachen.de&
scope=l2p.rwth userinfo.rwth"
https://oauth.campus.rwth-aachen.de/oauth2waitress/oauth2.svc/code

The response is returned in a JSON object:

{
    "device_code" : "BaUAJHPFYFi6wKU0WY5xLC",
    "user_code" : "SFW7WZXK7G",
    "verification_url" : "https://oauth.campus.rwth-aachen.de/manage",
    "expires_in" : 1800,
    "interval" : 5
}

The user_code and verification_url from the JSON object should be shown to your user. The idea is to ask the user to open a browser, navigate to the verification_url URL, and enter the user_code. The user_code is not case sensitive. The device_code, expires_in, and interval fields will be used in the next section.

When the user navigates to that URL authenticates and will see a page similar to the following:

After the user enters the user_code, the consent screen will be shown:

If the device is capable to open web pages in a browser, you may alternatively lead the user directly to the consent page by appending a query string to the verification url like this:

https://oauth.campus.rwth-aachen.de/manage/?q=verify&d=SFW7WZXK7G

If the user clicks "Authorize", then your application can obtain an access and refresh token that will grant your application access to the APIs of one or more information services. The scope parameter controls which information services your application can access.

Obtaining Access and Refresh Tokens

After your application has shown the user the user_code and the verification_url, your application may begin polling an endpoint with the device_code that was returned with the user_code and verification_url. The URL of the endpoint to poll is https://oauth.campus.rwth-aachen.de/oauth2waitress/oauth2.svc/token, and the interval between requests is specified as the interval in seconds. Such a request is shown below:

POST /oauth2waitress/oauth2.svc/token HTTP/1.1
Host: oauth.campus.rwth-aachen.de
Content-Type: application/x-www-form-urlencoded

client_id=QhV1IXlzticl9JCKgH01bhOMlu.app.rwth-aachen.de&
code=BaUAJHPFYFi6wKU0WY5xLC&
grant_type=device

or in CURL:

curl -d "client_id=QhV1IXlzticl9JCKgH01bhOMlu.app.rwth-aachen.de&
code=BaUAJHPFYFi6wKU0WY5xLC&
grant_type=device"
https://oauth.campus.rwth-aachen.de/oauth2waitress/oauth2.svc/token

If the user has not yet approved the request, the response will appear as follows:

{
    "status" : "error: authorization pending"
}

Your application should repeat these requests at the rate that does not exceed the value of interval field. If your application polls too quickly, then the response will appear as follows:

{
    "status" : "error: slow down"
}
        

Once the user logs in and grants your application access to an information service, the next polling request will result in an access and refresh token (shown below).

{
    "access_token" : "1bAiOVYtFmxSaOsSlwTh9o0ZUFK4AWS2FWQgmVhw3t1K9Mwc7aHTs2xdtXJ6PAgY",
    "token_type" : "Bearer",
    "expires_in" : 3600,
    "refresh_token" : "s4KJhlt9ON8jPJVgz3npdShhjDq5Ucu3coIZv5nkQajFcPL6ROpb4eSFftFga1Rf"
}

Upon receipt of this response, your application may use the access token in API requests. Access tokens have a limited lifetime. If your application needs access to an API over a long period of time, then it can use the refresh token to obtain a new access token (see Using a refresh token). If your application needs this type of access, then it should store the refresh token for later use.

Calling an API

After your application has obtained an access token, your application can access an API by including the token in either an access_token query parameter or an Authorization: Bearer HTTP header. When possible, it is preferable to use the HTTP Header, since query strings tend to be visible in server logs.

However not all information services at RWTH Aachen support both alternatives. Plese refer to the documentation of the information service API to find the right way of using the access token.

Please note that the given URLs are explanatory examples for calling an information service API at RWTH Aachen. Please refer to the documentation of the information service api to get actual URLs and parameters.

A call using the access_token Authorization: Bearer HTTP header looks like the following:

GET /api/courseinfo HTTP/1.1
Authorization: Bearer 1bAiOVYtFmxSaOsSlwTh9o0ZUFK4AWS2FWQgmVhw3t1K9Mwc7aHTs2xdtXJ6PAgY
Host: www2.elearning.rwth-aachen.de

A call to the UserInfo API using the access_token query string parameter looks like the following:

GET https://www2.elearning.rwth-aachen.de/api/courseinfo?access_token=1bAiOVYtFmxSaOsSlwTh9o0ZUFK4AWS2FWQgmVhw3t1K9Mwc7aHTs2xdtXJ6PAgY

You can try either out in the CURL command line application. Here's an example of the query string parameter option:

curl https://www2.elearning.rwth-aachen.de/api/courseinfo?access_token=1bAiOVYtFmxSaOsSlwTh9o0ZUFK4AWS2FWQgmVhw3t1K9Mwc7aHTs2xdtXJ6PAgY

And the HTTP header option:

curl -H "Authorization: Bearer 1bAiOVYtFmxSaOsSlwTh9o0ZUFK4AWS2FWQgmVhw3t1K9Mwc7aHTs2xdtXJ6PAgY" https://www2.elearning.rwth-aachen.de/api/courseinfo

Using a Refresh Token

Access tokens expire. An API will indicate that an access token has expired when it returns a 401 status code. To obtain a new access token, make a request to the token endpoint and include the client_id, refresh_token, and grant_type parameters (shown below).

POST /oauth2/oauth2.svc/token HTTP/1.1
Host: service.campus.rwth-aachen.de
Content-Type: application/x-www-form-urlencoded

client_id=QhV1IXlzticl9JCKgH01bhOMlu.app.rwth-aachen.de&
refresh_token=s4KJhlt9ON8jPJVgz3npdShhjDq5Ucu3coIZv5nkQajFcPL6ROpb4eSFftFga1Rf&
grant_type=refresh_token

A successfull call will return a JSON formatted response containing a new access_token. Use the new access_token for procceeding requests to information service APIs.

{
    "status" = "ok",
    "expires_in" = 3600,
    "access_token" = "cvY0kDk3BOO4IlVS6i8PtBXmgO3eSFQrNEUWoRMaCz9xl4N55GNlKqSEcvt5iHi",
    "token_type" = "bearer"
}

For the users security the refresh tokens will also expire after 6 months. Your application then needs to guide the user through the authorization process again. Once your refresh token is expired the response from the token endpoint will be as follows:

{
    "error": "authorization invalid."
}

Token Info Validation

Once you obtained an access_token you can check it for validity using the token info endpoint.

POST /oauth2waitress/oauth2.svc/tokeninfo HTTP/1.1
Host: oauth.campus.rwth-aachen.de
Content-Type: application/x-www-form-urlencoded

client_id=QhV1IXlzticl9JCKgH01bhOMlu.app.rwth-aachen.de&
access_token=BaUAJHPFYFi6wKU0WY5xLC

or in CURL:

curl -d "client_id=QhV1IXlzticl9JCKgH01bhOMlu.app.rwth-aachen.de&
access_token=BaUAJHPFYFi6wKU0WY5xLC"
https://oauth.campus.rwth-aachen.de/oauth2waitress/oauth2.svc/tokeninfo

The TokenInfo endpoint will respond with a JSON array that describes the token or an error.

{
     "status": "ok",
     "audience": "Your App Name",
     "scope": "l2p.rwth userinfo.rwth",
     "expires_in": 3250,
     "state": "valid"
}

Token Invalidation

If you do not need access to the API anymore you may invalidate your access and refresh tokens. Once invalidated you can no longer use the tokens to call any informationservices. However you can use the device workflow again to obtain new refresh and access tokens.

To invalidate the token you send an HTTP POST to the OAuth 2.0 token endpoint at https://oauth.campus.rwth-aachen.de/oauth2waitress/oauth2.svc/token using your client_id, refresh_token and the grant_type of invalidate. The following is an example for a token invalidation call:

POST /oauth2/oauth2.svc/token HTTP/1.1
Host: service.campus.rwth-aachen.de
Content-Type: application/x-www-form-urlencoded

client_id=QhV1IXlzticl9JCKgH01bhOMlu.app.rwth-aachen.de&
refresh_token=s4KJhlt9ON8jPJVgz3npdShhjDq5Ucu3coIZv5nkQajFcPL6ROpb4eSFftFga1Rf&
grant_type=invalidate

Anonymous Workflow

To access anonymous information services of RWTH Aachen University you also need an access token to ensure that only valid applications access the APIs. You have two options:

  • Use a personalized token to access the anonymous API. Every personalized token will also work to access anonymous APIs.
  • Use an anonymous token to access the anonymous API as described in this section.

The anonymous workflow does not involve any interaction with the user. The access token can be directly obtained from the OAuth 2 server. As the personalized access token the anonymous access token is only valid for 30 minutes and needs to be renewed using the anonymous workflow again.

Obtaining an Anonymous Access Token

You will first need to register your application here. To proceed with this flow, you will need the client_id created during application registration, and you will need to embed them in your application.

After you have the client_id, you send an HTTP POST to the OAuth 2.0 endpoint at https://oauth.campus.rwth-aachen.de/oauth2waitress/oauth2.svc/token with your client_id. The following is an example request for a user code:

POST /oauth2waitress/oauth2.svc/token HTTP/1.1
Host: oauth.campus.rwth-aachen.de
Content-Type: application/x-www-form-urlencoded

client_id=QhV1IXlzticl9JCKgH01bhOMlu.app.rwth-aachen.de&
grant_type=anonymous

or in CURL:

curl -d "client_id=QhV1IXlzticl9JCKgH01bhOMlu.app.rwth-aachen.de&
grant_type=anonymous"
https://oauth.campus.rwth-aachen.de/oauth2waitress/oauth2.svc/token

The response is returned in a JSON object:

{
    "access_token" : "LMFQyC8S2uFq0DmfFgUF",
    "expires_in" : 1800,
    "token_type" : bearer
}

Upon receipt of this response, your application may use the access_token in API requests. Access tokens have a limited lifetime. If your application needs access to an API over a longer period of time, then it can use the anonymous workflow again to obtain a new access token.

Calling an anonymous API

See Calling an API.

Endpoint Description

In this section you can find a description of the endpoints and their parameters used for authorization. For a reference on how to use them please refer to the sections describing the different workflows. In general all Methods accept parameters only in the HTTP POST body formatted as application/x-www-form-urlencoded. The endpoints will return objects containing the given return values as fields in JSON formatting.

Please note: The displayed return values show the minimal set of information that is obtained when calling the endpoint. There may be additional fields, such as diagnostics and status information, available in the returned object.

Code Endpoint

The code endpoint is used to request codes that can be shown to the user in order to authorize the application. To call the code endpoint send a HTTP POST request to https://oauth.campus.rwth-aachen.de/oauth2waitress/oauth2.svc/code and specify the following parameters:

Parametes

Name Type Description
client_id string Your client id.
scope string The scopes your app needs access to. Multiple scopes are separated by spaces.

Returns

Name Type Description
device_code string A code that identifies your devices authorization request.
user_code string A code that the user needs to enter when authorizing your app. You may also append this code to the verification url to make the authorization process easier for the user if a webbrowser is available on the device.
verification_url string The verification URL needs to be accessed by the user in a browser to authorize your app. To make the authorization process easier for the user you can append ?q=verify&d={user_code} to the url and direct the user to URLs directly.
expires_in int Ammount of time the user_code and the device_code remain valid in seconds.
interval int The number of seconds to wait in between subsequent polling calls.

Token Endpoint

The token endpoint is used to manipulate access tokens during and after the authorization process. To call the code endpoint send a HTTP POST request to https://oauth.campus.rwth-aachen.de/oauth2waitress/oauth2.svc/token and specify the following parameters:

Parametes

Name Type Description
client_id string Your client id.
grant_type enum Defines the kind of manipulation you want to perform on the token. Valid values are:
authorization_code
reserved for server and web application workflow. currently not supported.
refresh_token
for a given refresh_token create a new access_token. The old access token is invalidated.
device
for a given device code as specified by the device workflow get an access and a refresh token.
anonymous
create a new anonymous acces token as specified by the anonymous workflow.
claim
create a new personalized access token as specified by the claim workflow.
invalidate
remove all authorizations granted for a given refresh token and derived access tokens.
refresh_token string Only for grant_type=refresh_token|invalidate: The refresh token recieved by your app.
code string Only for grant_type=device: The device code obtained from the token endpoint.
deviceName string Only for grant_type=device|claim, optional: A user readable name of the device the app is curently running on.
deviceOS string Only for grant_type=device|claim, optional: Name of the device OS e.g. android, ios, wp8, ....
claim JWT Only for grant_type=claim: The claim that is used to issue the access token. Formatted as JSON Web Token (JWT).

Returns

Name Type Description
refresh_token string The token your app needs to obtain new access tokens.
access_token string The token your app needs to communicate to information services.
expires_in int Time in seconds until the access_token is automatically invalidated and needs to be renewed using the token endpoint.

TokenInfo Endpoint

The token info endpoint supplies information about your current token. To call the token info endpoint send a HTTP POST request to https://oauth.campus.rwth-aachen.de/oauth2waitress/oauth2.svc/tokeninfo using the following parameters:

Parametes

Name Type Description
client_id string Your client id.
access_token string The current access_token of your app.

Returns

Name Type Description
audience string The readable name of your application.
expires_in int Ammount of time the access_token remains valid in seconds.
state enum One of the following:
valid
The access_token is valid and can be used to access information services.
expired
The supplied access_token is expired or the authorization was removed by the user.
scope string Space separated list of scopes valid for the access_token.
interval int The number of seconds to wait in between subsequent polling calls.

Authorize Endpoint

The authorize endpoint is used to authorize tokens for serverside and web applications. It can be called from the URL https://oauth.campus.rwth-aachen.de/oauth2waitress/oauth2.svc/authorize. This endpoint is not intended to be called as a webservice method. The user should be redirected (e.g. by clicking a link) to the URL. After the authorization is complete the user will be redirected to the supplied redirect_url.

Parametes

Note: The parameters have to be transferred in the query string using a HTTP GET request.
Name Type Description
client_id string Your client id.
response_type enum
token
Create an access token using the web application workflow.
code
reserved for server workflow. currently not supported.
scope string The scopes your app needs access to. Multiple scopes are separated by spaces.
state string Any state that might be useful to your application upon receipt of the response.
redirect_uri string The base URL that the user will be redirected to after authorization is complete.

Returns

Note: The return values are appended as a query string to the redirect_url in the following way: {redirect_url}?access_token={access_token}&expires_in={expires_in}&state={state}.
Name Type Description
access_token string The token your app needs to communicate to information services.
expires_in int Ammount of time the access_token remains valid in seconds.
state string The state that was given when starting the request.

Last update 2015-04-24.

Portions of this page are reproduced from work created and shared by Google and used according to terms described in the Creative Commons 3.0 Attribution License.