---
# System prepended metadata

title: WIPP API client

---

# WIPP API client

Feature branch (WIP): https://github.com/ktaletsk/data-tools/tree/feat/wipp-api-client-0.1.0/wipp_client

## Keycloak support

### Keycloak local setup

1. Start the Keycloak container
```shell=bash
docker run -p 8081:8080 -e KEYCLOAK_USER=admin -e KEYCLOAK_PASSWORD=admin quay.io/keycloak/keycloak:11.0.2
```
2. Login to Keycloak UI: http://127.0.0.1:8081/auth/admin/master/console
3. Create new Realm by importing [this config](https://github.com/usnistgov/WIPP-backend/blob/master/docs/auth-acl/realm-export.json)
4. Create new user: ktaletsk. Set the user password


### Keycloak concepts

- Realm
- User
- Group
- Role
- Role Mapping

### To get sample app running

Here I am referring to the [sample app](https://github.com/ktaletsk/Keycloak-Identity-and-Access-Management-for-Modern-Applications/tree/master/ch2) from book *Keycloak - Identity and Access Management for Modern Applications*

- Keycloak up and running
- A realm named `myrealm`
- A global role named `myrole`
- A user with the preceding role
- Create client in Keycloak
    - Client ID: `myclient`
    - Client Protocol: openid-connect (default)
    - Root URL: `http://localhost:8000`

### OAuth 2.0 protocol flow for WIPP API
There are four roles defined in OAuth 2.0:

- Resource owner: the end user that owns the resources an application wants to access. In our case: LabShare users.
- Resource server: the service hosting the protected resources. In our case: WIPP API backend
- Client: This is the application that would like to access the resource. In our case WIPP API client.
- Authorization server: This is the server issuing access to the client, which is the role of Keycloak.

### OpenID Connect protocol flow for WIPP API:

- End User: This is the equivalent of the resource owner in OAuth 2.0. It is, of course, the human being that is authenticating.
- Relying Party (RP): A somewhat confusing term for the application that would like to authenticate the end user. It is called the relying party, as it is a party that is relying on the OpenID Connect Provider to verify the identity of the user.
- OpenID Provider (OP): The identity provider that is authenticating the user, which is the role of Keycloak.

Relying Party requests the identity of the end user from the OpenID Provider. As it builds on top of OAuth 2.0 at the same time as the identity of the user is requested, it can also obtain an access token

### Simple Python client

Prereqs:
- Keycloak running at http://localhost:8081/auth/
- Realm named `<realm_name>`
- Public client named `<client_name>`
- User `<user>` with password `<password>` 

```python=3.9
from keycloak import KeycloakOpenID

# Configure client
keycloak_openid = KeycloakOpenID(server_url="http://localhost:8081/auth/",
                    client_id=<client_name>,
                    realm_name=<realm_name>)

# Get Token
token = keycloak_openid.token(<user>, <password>)
print(token)

# Get some information about the user
userinfo = keycloak_openid.userinfo(token['access_token'])
print(userinfo)
# Output: {'sub': '<id>', 'email_verified': False, 'name': 'Konstantin Taletskiy', 'preferred_username': 'ktaletsk', 'given_name': 'Konstantin', 'family_name': 'Taletskiy', 'email': 'konstantin.taletskiy@labshare.org'}
```

### Local stack deployment with Docker
1. Create storage folders
```sh
mkdir wipp-mongo-volume
mkdir wipp-backend-data
```
2. Create Docker network
```sh
docker network create wipp-network
```
3. Run Mongo container 
```sh
docker run --rm -v $(pwd)/wipp-mongo-volume:/data/db -p 27017:27017 --name wipp-mongo -d --network=wipp-network mongo:3.6
```
4. Run Keycloak container
```sh
docker run -p 8081:8080 -e KEYCLOAK_USER=admin -e KEYCLOAK_PASSWORD=admin --name wipp-keycloak -d --network=wipp-network quay.io/keycloak/keycloak:11.0.2
```
5. Configure Keycloak
    - Create WIPP Realm from included config
    - Create user
    - Set user password
6. Run WIPP-backend container
```sh
docker run --rm -v $(pwd)/wipp-backend-data:/data/WIPP-plugins -p 8080:8080 -e KEYCLOAK_AUTH_URL=http://wipp-keycloak:8080/auth -e KEYCLOAK_SSL_REQUIRED="external" -e KEYCLOAK_DISABLE_TRUST_MANAGER="false" --network=wipp-network --name wipp-backend wipp-backend wipp-mongo 27017 WIPP_PVC_NAME_VALUE
```
7. (Optional) WIPP-frontend
```sh
docker run --rm -p 8989:80 -e KEYCLOAK_URL=wipp-keycloak:8080/auth -d --network=wipp-network --name wipp-frontend wipp/wipp-frontend:3.0.1 http://wipp-backend 8080
```

8. WIPP API client
```sh
docker run --rm -v $(pwd)/wipp-api-keycloak.py:/home/wipp-api-keycloak.py -v /Users/taletskiyk2/git/data-tools/wipp_client:/home/client --network=wipp-network -it python bash
cd home/
pip install requests python-keycloak client/


export WIPP_API_INTERNAL_URL=http://wipp-backend:8080/api
```