· 7 years ago · Jun 11, 2018, 02:18 PM
1[](https://codevault.io/kaeuferportal/auth/builds)
2
3# Auth
4
5Dieses Projekt dient dazu die Rechte der User für unsere Applikationen
6zu verwalten. Außerdem dient es unseren anderen Applikationen als OAuth2
7Authentication Server.
8
9Das Projekt ist hier zu finden: https://auth.kaeuferportal.de/
10
11## Verwandte Projekte
12
13[**omniauth_kaeuferportal**](https://github.com/crahles/omniauth-kaeuferportal):
14OmniAuth Strategy to enable another application to use **Auth** for authentication.
15
16[**auth_connector**](https://codevault.io/kaeuferportal/auth_connector):
17A gem that allows another application to use **Auth** for authorization.
18
19[**access_token_agent**](https://codevault.io/kaeuferportal/access_token_agent):
20A gem that allows an application to receive an access token from **Auth**
21using the client credentials flow.
22
23## OAuth2 101
24
25### Relevant endpoints of the Auth Service
26
27#### Access Token endpoint
28
29````
30/oauth/token
31````
32
33This endpoint is provided by doorkeeper and allows clients to obtain an access
34token. It is specified in the [OAuth2 specification](https://tools.ietf.org/html/rfc6749#section-3.2).
35
36#### UserInfo endpoint
37
38````
39/api/users/current
40````
41
42This endpoint is implemented by us. When called with an access token, it provides
43details about the user associated with that access token (e.g. mail address or name).
44
45This endpoint is inspired by the [OpenID Connect UserInfo Endpoint](http://openid.net/specs/openid-connect-core-1_0.html#UserInfo).
46It follows the OIDC specification as far as possible
47Though we are not really doing OpenID Connect, it wont hurt to be compatible when possible.
48
49#### Application Access endpoint
50
51````
52/api/applications/:client_id/current_access
53````
54
55This endpoint is implemented by us. When called with an access token, it provides
56details about the privileges the user (or application) associated with that access token
57should gain on the application specified in the path.
58
59Currently there is only a single key called `access`, which binarily specifies
60whether the access token allows to access the application or not.
61
62### As seen by our Applications
63
64Given you are writing an application that wants to perform authentication using
65the auth service. We have two typical use cases here.
66
67#### Use case 1: API-Authentication using a Bearer Token
68
69Your application will directly receive a bearer token from its client and can
70validate the token, by asking the auth service which privileges the bearer of
71this token should have (Use the `auth_connector` for that).
72
73**Note:** Access tokens can be granted to users and applications, but usually
74you should not need to care to whom the token belongs, as long as you are only
75interested in *authorization* information (i.e. "is it allowed to access my resource?").
76
77#### Use case 2: Web-based Authentication with a present user
78
79In this scenario, you will usually use our omniauth gem. A user browsing your
80application can be redirected to the auth service using the *[OAuth2 Authorization Code flow](https://tools.ietf.org/html/rfc6749#section-1.3.1)*.
81The user will authenticate with the auth service, which allows your application
82to obtain the access token itself (using an authorization code) and use this access
83token to fetch details about the user (name, E-Mail, etc) and his privileges.
84
85### As seen by the client of an API
86
87Given you are writing a client that wants to access the API of another application,
88which uses the auth service. You will have to perform two steps.
89
90#### Step 1: Obtain an access token
91
92To obtain an access token you have two choices: Either get one using the *authorization code
93flow* (e.g. using omniauth). Such an access token would grant you the privileges of the
94user for whom the access token is granted.
95Option 2 is to obtain an access token using the *[client credentials flow](https://tools.ietf.org/html/rfc6749#section-1.3.4)*. This way
96you obtain the privileges that are granted for your client, without any associated user.
97For the latter flow see the [access token agent](https://codevault.io/kaeuferportal/access_token_agent).
98
99Example request to obtain an access token using client credentials:
100````
101POST /oauth/token HTTP/1.1
102Host: auth.kaeuferportal.de
103Authorization: Basic ThisIsYourBase64EncodedClientIdAndClientSecret
104Content-Type: application/x-www-form-urlencoded
105
106grant_type=client_credentials&=
107````
108
109#### Step 2: Present the access token on every request
110
111After obtaining the access token, just present it as a bearer token on every request
112to the application:
113
114````
115POST /example/api
116
117Authorization: Bearer YourAcessTokenGoesHere
118````
119
120## Neue App hinzufügen
121
122Beim Hinzufügen einer neuen App müssen die folgenden Attribute vergeben werden:
123
124* **Name**: Menschenlesbare Referenz auf die Anwendung
125* **Client-ID**: Eindeutiger Bezeichner für die Anwendung, der in API Requests etc. genutzt wird
126* **Redirect-URI**: Sollte auf die (Omniauth) Callback-URL der Anwendung verweisen.
127 Falls die Anwendung keine Authentifizierung nutzt, genügt `urn:ietf:wg:oauth:2.0:oob`
128
129## Single Sign-out
130
131This application has a contract to enable single sign-out. This is the opposite of
132single sign-on: As soon as users log out of one application that is authenticated
133via auth, they are logged out of all other applications as well.
134
135The contract to support single sign-out is simple: The application **MUST ALWAYS**
136redirect to the logout URL of the authentication server (e.g. https://auth.kaeuferportal.de/logout),
137when the application's logout URL (e.g. `/logout`) is called.
138Prior to redirection, the application **MUST** destroy the local session of the user, if it
139exists.
140
141Applications that obey this contract **SHOULD** have their `logout_uri` (e.g. https://myapp.kaeuferportal.de/logout)
142registered with the authentication server.
143
144### Implications
145
146This means the actual logout of the user will be a star-shaped redirect chain,
147which first goes from an application to auth, then to the next application and back to auth,
148repeating until all applications have signed out the user.
149
150## Setup in Development Environment
151There's a known issue with the db seeding and ```authlogic``` gem. To setup the database locally, run the following command:
152
153```
154bundle exec rake db:create db:schema:load; bundle exec rake db:seed
155```
156
157You can read more about the issue here - https://github.com/binarylogic/authlogic/issues/88