Welcome dev@localhost

Here you can find all the information needed to get started using OAuth 2.0 to access our services.

Already familiar with OAuth 2.0? Go to the admin section to register a client and start developing your application.

Quick-start URLs

OAuth 2.0 authorization server metadata: https://oauth2-scipro-158-spec-demo2.branch.dsv.su.se/.well-known/oauth-authorization-server
OpenID Connect metadata: https://oauth2-scipro-158-spec-demo2.branch.dsv.su.se/.well-known/openid-configuration
Authorization endpoint: https://oauth2-scipro-158-spec-demo2.branch.dsv.su.se/oauth2/authorize
Token endpoint: https://oauth2-scipro-158-spec-demo2.branch.dsv.su.se/oauth2/token
Token introspection endpoint: https://oauth2-scipro-158-spec-demo2.branch.dsv.su.se/oauth2/introspect
User info endpoint: https://oauth2-scipro-158-spec-demo2.branch.dsv.su.se/oidc/userinfo

What is OAuth 2.0?

If you want a more detailed explanation you can read the Wikipedia article on OAuth 2.0, for a simpler explanation read below.

In the simplest term it answers the question What data is the application allowed to access? To explain, let's first define some roles used in OAuth 2.0.

Resource owner: A person who owns some data.
Resource server: Holds data owned by the resource owner.
Client: An application that wants to access the protected data, or act on the resource owners behalf.

Example: read your course grades, or email (access data)
Example: add a new meeting to your calendar (act on your behalf)
Authorization server: The service that gets permissions from the resource owner and forwards them to the client. You are currently reading information on DSV's authorization server.

A basic example from a resource owners perspective

Let's take the example of a calendar application, where the resource owner is you, the resource server is a calendar service, and the client is the application that wants to see what you've scheduled and be able to schedule new meetings.

You (resource owner) go to the calendar application (client)
The application needs to access your personal schedule (data on the resource server)
It sends you to the authorization server to get permission
The authorization server asks you to identify yourself (log in with your Stockholm University account)
It then asks you if you want to give the calendar application permission to access your calendar
If you agree, the authorization server gives the application a token that looks something like this:
```
user: dev@localhost
scope: calendar
```
The application presents this token to the resource server
The resource server verifies the token and sees that it is your token and that you've given calendar permission and responds with your personal calendar information

Creating an application that accesses protected data from a developer perspective

Let's take the example of a calendar application, where the resource owner is some other person, the resource server is a calendar service, and the client is the application that you're creating. The application wants to see what the person using the application has scheduled and be able to schedule new meetings.

Register a new client for your application
Once the client is created you will be presented with a "client id" and a "client secret". These are confidential credentials, and you need to store them appropriately. You will not be able to access your client secret again.
To get an access token you need to redirect the user to the authorization server with the proper parameters. If you view your registered client you will see the full URL you need to redirect the user to.
Once the user has authorized your application, the authorization server will redirect the user back to your application (the registered redirect URI) with a one time code.
Present the code, along with the credentials from step 2, to the authorization server to get an access token.
Send a request to the resource server with the access token to get the data you need.

Creating a resource server from a developer perspective

As a resource server the one thing you need to do, and it is very important that you do, is to verify the access token before trusting it. There are two ways to do this, either by introspection or by using the public key of the authorization server to verify the token.

How the token is presented is up to you but the recommended way is as a bearer token in the Authorization HTTP header.

Public key verification

Strongly recommended to use existing robust and well-tested libraries to perform these steps. See library section at https://jwt.io for a plethora of libraries in different languages.

Public key verification can be done completely locally within the resource server. It does not require the authorization server to be online since it sends no network requests, and it does not require slow credential verification. It is however more complex to set up than the token introspection.

The following steps can, and probably should, be done once and the keys stored until there is a reason to update them. If the resource server is presented with a JWT that, in its header, specifies a key that is not match the downloaded keys there is a high probability that the token is invalid. If you register your client with the authorization server you will be contacted if the keys are updated.

Download the metadata from /.well-known/oauth-authorization-server
Parse the response and extract the jwks_uri attribute
Download the JWKS from the given URI
Parse and store the presented keys

Once you have the public key you can use it to verify incoming tokens. The token is a JWT. Once a JWT is presented follow these steps:

Parse the header
Find the key ID to determine what key was used to sign (kid parameter)
Find the key from the among the downloaded keys in the JWKS
Verify the signature

Token introspection

Token introspection is a simple way to verify the token. It requires the authorization server to be online, and it requires the resource server to send a network request to the authorization server. It is a fine choice for low throughput services, for example if all you need is the subject when the end user logs in. However, using it for a "standard" JSON over HTTP API is not recommended as it will add a lot of overhead and reliance on other servers being online to every single request.

First you need to register your resource server with the authorization server. Save and securely store the client id and client secret, you will not be able to access the client secret again.

To use token introspection you need to send a request to the authorization server with the access token and the client credentials. The client credentials should be presented as a basic authentication in the Authorization HTTP header. The token is sent as a form parameter with the name token.

The token introspection endpoint is located at POST /oauth2/introspect

DSV OAuth 2.0 authorization server