id4me-client

Id4me client

Proof of concept client for Id4me. It can be used as a standalone client to secure an existing service or as a library to add Id4me support directly into an application.

Securing an existing application

Using Nginx and the auth_request module, the client can be used out of the box to restrict an service to authenticated used only. Here is a configuration snippet that can be used as a base to configure Nginx.

upstream id4me-client {
  server localhost:8000 max_fails=5 fail_timeout=60s;
}

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;

    server_name myservice.example.com;

    auth_request /auth/me;
    error_page 401 = @error401;

    location @error401 {
        return 302 https://$host/auth/login?redirect_uri=$scheme://$host;
    }

    location /auth {
        proxy_pass http://id4me-client:8000/auth;
    }
}

To further restrict the access and only allow users from a specific domain you can use the allowed_domains property of the client configuration file:

id4me_client:
  allowed_domains:
    - example.com

This setup can also be used to secure multiple services, in this case the authentication service will probably be hosted on a separated domain:

upstream id4me-client {
  server localhost:8000 max_fails=5 fail_timeout=60s;
}

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;

    server_name sso.example.com;

    location / {
        proxy_pass http://id4me-client:8000/;
    }
}

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;

    server_name myservice.example.com;

    auth_request /auth/me;
    error_page 401 = @error401;

    location @error401 {
        return 302 https://sso.example.com/auth/login?redirect_uri=$scheme://$host;
    }

    location /auth {
        proxy_pass https://sso.example.com/;
    }
}

In this case the authentication session cookie must be shared accross the mutliple services under the example.com domain. This can be done by setting the cookie_domain property of the client configuration:

id4me_client:
  cookie_domain: .example.com # leading dot is mandatory for the cookie to be set also for subdomains

Introspection endpoint (/auth/me)

Using the client cookie an application can use the introspection endpoint to fetch the user's claims.

$ BASE_URL=https://sso.example.com
$ SESSION=<session cookie value here>
$ curl "$BASE_URL/auth/me" -H 'Accept: application/json' --cookie session=$SESSION | jq
{
  "given_name": "Titi",
  "id4me.identifier": "titi.id4me-tests.rd.nic.fr",
  "iss": "api.rd.nic.fr/id4me/authority",
  "nickname": "Titi (but its a nickname)",
  "sub": "a490b8ae-671a-4092-9818-811f3d7a097d"
}