Commit 1d8be035 authored by Geert-Johan Riemer's avatar Geert-Johan Riemer

Merge branch 'feature/528-add-OAS-spec-authorization' into 'master'

#528 outway: added authorization interface specification

See merge request !400
parents 1f3d4317 975882cb
Pipeline #57049553 failed with stages
in 36 minutes and 42 seconds
---
title: "Authorization"
description: ""
weight: 20
menu:
docs:
parent: "further-reading"
---
## Introduction
To enable authorization, organizations can plug-in their own authorization service to an outway. Once configured, all requests will be authorized by this service before routing the request to the targeted API in the NLX network.
## How it works
Once an authorization service is configured the outway will, after receiving a request from an application, extract all the HTTP-headers from the request. Only the HTTP headers along with the destination organization and service will be send to the authorization service. The authorization service can use this information to determine if authorization should be granted. The authorization service will send the result back to the the outway. If the authorization is granted the outway will strip the HTTP headers starting with `X-NLX` from the request and continue sending the request (body + HTTP headers) to the destination inway.
## The authorization interface
In order to keep the NLX components as flexible as possible, each organization will have to implement the "authorization interface" on their own authorization service. Implementing this interface will enable communication between the outway and the authorization service.
We have described this interface using Open API Specification (OAS). [This specification can be found here](https://gitlab.com/commonground/nlx/tree/master/outway/authorization-interface.yaml).
A reference implementation has also been made available in the [NLX repository](https://gitlab.com/commonground/nlx/blob/master/auth-service/).
## Configuring the outway
After you have implemented the `authorization interface` on your authorization service, you will have to configure the outway to use it. This can be done by setting the environment variable `AUTHORIZATION_SERVICE_ADDRESS` in the docker image of the outway. This variable should contain the URL of your authorization service.
For example, the URL of our authorization service is `https://auth.nlx.io`, we can start the outway by running the following docker command:
```bash
docker run --detach \
--name my-nlx-outway \
--volume ~/nlx-setup/root.crt:/certs/root.crt:ro \
--volume ~/nlx-setup/org.crt:/certs/org.crt:ro \
--volume ~/nlx-setup/org.key:/certs/org.key:ro \
--env DIRECTORY_INSPECTION_ADDRESS=directory-inspection-api.demo.nlx.io:443 \
--env TLS_NLX_ROOT_CERT=/certs/root.crt \
--env TLS_ORG_CERT=/certs/org.crt \
--env TLS_ORG_KEY=/certs/org.key \
--env AUTHORIZATION_SERVICE_ADDRESS=https://auth.nlx.io \
--env AUTHORIZATION_ROOT_CA=~/nlx-setup/root.crt:/certs/root.crt:ro \
--env DISABLE_LOGDB=1 \
--publish 4080:80 \
nlxio/outway:latest
```
Please note we are also setting the environment variable `AUTHORIZATION_ROOT_CA`. This variable contains the path to a root Certificate Authority(CA). To keep everything as secure as possible, your authorization service **must** only accept connections with TLS enabled. The configured root CA will be used by the outway to verify the certificates of your authorization service.
## Headers
HTTP-headers are used to pass around authorization information. NLX provides a set of HTTP-headers which will be logged in the transaction-log and stripped from any request as soon as this request leaves the organization.
- `X-NLX-Requester-User` should contain information about the user, for example a userID
- `X-NLX-Requester-Claims` should contain claims granted to the user
- `Proxy-Authorization` should contain the credentials to authenticate a user or application with a server. For example, a JWT token. This header will **always** be stripped, even if the request does not leave the organisation. Take a look at the [Mozilla Proxy-Authorization header documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Proxy-Authorization) for more information about this header.
openapi: 3.0.0
info:
description: |
The outway has the option to configure a authorization service. Once configured, the requests going through the outway will be authorized by this authorization service.
In order to enable communication between the outway and their authorization service, each organization is required to implement the interface described in this specification on their authorization service.
version: "1.0.0"
title: Authorization
paths:
/auth:
post:
summary: Authorization request
responses:
200:
description: The authorization request has been handled successfully. This does not mean the request is authorized, it means that the request has been processed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/AuthorizationResponse'
requestBody:
$ref: '#/components/requestBodies/AuthorizationRequest'
components:
schemas:
AuthorizationRequest:
type: object
properties:
headers:
type: object
additionalProperties:
type: array
items:
type: string
description: Contains the HTTP-headers of the request made to the outway
organization:
type: string
description: organization targeted by the request send to the outway
service:
type: string
description: service targeted by the request send to the outway
AuthorizationResponse:
type: object
properties:
authorized:
type: boolean
description: true if the request is authorized. The outway will continue to send the request to the targeted service. false when the authorization has failed for whatever reason. The outway will return a 401 to the requesting client.
reason:
type: string
description: If the authorization has failed this field can be used to explain why. This field will be send to the client responsible for the original request.
requestBodies:
AuthorizationRequest:
content:
application/json:
schema:
$ref: '#/components/schemas/AuthorizationRequest'
description: The body of the request send to the authorization service
required: true
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment