COOPGO Mobility Accounts

COOPGO Mobility Accounts is a webservice handling profiles management on the COOPGO Technical Platform.

It supports the CMS standard for accounts data and a flexible data model to extend its functionalities.

It provides :

• Accounts data management and basic authentication/identification functionalities
• a gRPC API for accounts management (Create, update, delete, manage credentials, ...)
• an OAuth2 / OpenID Connect Provider based on Ory Fosite library
• Flexible account data models using JSON schemas to handle the CMS standard and to be extended for other or specific use cases

What is expected in a near future :

• An OpenID connect client to link accounts to other identification providers
• An integration mechanism to share account data with other services through APIs

What it's not and will not be (others do it much better !) :

• a full featured identity management platform
• a UI to manage accounts (you will have to create your own UIs / applications to interact through gRPC with COOPGO Mobility Accounts)

This project is under development and not stable yet.

Getting started

Run locally

COOPGO Mobility Accounts can be configured through a config.yaml (other formats might be supported). Many defaults already exist but you must provide some configuration for example if you need to enable OpenID Connect.

Example of config.yaml file targetting a mongodb database :

dev_env: true

storage:
  db:
    mongodb:
      host: user:password@localhost

services:
  oidc_provider:
    enable: true
    csrf_key: 32-byte-long-auth-key-----------
    port:     8091
    namespaces: 
      default:
        namespace: default
        secret_key: some-cool-secret-that-is-32bytes
        templates_dir: oidc-provider/templates/default
        match_claims: 
          "urn:cms:personal-informations:read": personal_information
          "urn:cms:civil-status:read": civil_status
          "urn:cms:favorites:read": favorites
          "urn:cms:driving-licence:read": driving_licence
          "urn:cms:ice-contacts:read": ice
        clients: 
          - id: abcdef
            oidc: true
            secret: $2y$10$0GwBc17u9HjZnVlFjhIv2u.Jq..5NyzdUENpGa8jUtok2zHj/STmm # ghijkl
            token_endpoint_auth_method: client_secret_post
            response_types: 
              - code
            grant_types:
              - authorization_code
            redirect_uris: 
              - https://psteniusubi.github.io/oidc-tester/authorization-code-flow.html
            scopes: 
              - openid 
              - profile 
              # - urn:cms:personal-informations:read

You must have a mongodb database and of course change the credentials. You might also change the values of the openid client example.

For testing purpose, you can then directly run with (make sure you have Go version >= 1.18) :

go run .

You can then test the service through :

• the gRPC API listening on http://localhost:8090 (using Postman for example) or the grpcclient example in folder examples/grpcclient
• the OpenID Connect providers listening on http://localhost:8091

What is an account in COOPGO Mobility Account

An account is, in COOPGO Mobility accounts, simply a set of datas, that you will be able to manage through a gRPC API (this could be extended with REST later but it's not our priority at COOPGO, so feel free to contribute ...).

In addition, but optionnally (an account can exist without any login mechanism), the service provides authentication through gRPC requests or OpenID Connect.

Accounts data management

Accounts Data is represented by key-value pairs.

We can assign JSON schemas to keys in the configuration to validate associated values.

Default configuration is visible in the file config.go. It handles the CMS standard schemas.

These key-value pairs can be accessed and managed through gRPC requests, and can also be linked to OpenID Connect claims/scopes to share them with external applications.

Accounts namespaces

COOPGO Mobility Accounts can handle multiple accounts environments (or set of users) with "namespaces", for example to handle multiple applications sharing the same service deployment (a little bit like "realms" in Keycloak), or different kind of accounts within the same application.

Authentication

Local authentication

This service provides a "local authentication mechanism", storing account credentials in the database.

OpenID Connect client

TODO

In the future, this service will support connecting through an external OpenID Connect provider.

OpenID Connect provider

The internal OpenID Connect provider lets you provide authentication and identity to external applications. Clients are defined in the configuration (you will have to change the configuration to add a client : we don't want to manage this dynamically through a database "by design", to be "stateless" on the OIDC provider base configuration)

The OIDC provider needs Etcd v3 (see below for storage considerations)

Storage options

Accounts management

COOPGO Mobility Accounts supports the following databases for storage :

• MongoDB
• PostgreSQL

SQL schema

SQL schema for PostgreSQL is available from file storage/postgresql/schema.hcl in the atlasgo Data Definition Language format

To set your development DB with this schema easily, you can simply use atlasgo CLI :

atlas schema apply --url "postgresql://username:password@localhost:5432/coopgo_platform?sslmode=disable"

OpenID Connect provider

You need a running Etcd v3 to enable the OpenID Connect provider.

As for accounts management, the OpenID Connect provider is divided in namespaces, providing 1 OIDC provider per namespace.

For example :

• https://auth.mymobilityaccounts/default/auth would be the authentication endpoint for accounts from the "default" namespace, https://auth.mymobilityaccounts/default/token for the token endpoint, etc...
• https://auth.mymobilityaccounts/app1/auth would be the authentication endpoint for accounts from the "app1" namespace ...
• etc...

You will have to define different clients for each of these namespaces. From the client perspective, if you need to provide identification for multiple "namespaces", then you will have to set up multiple providers (1 per namespace).

For each namespace, you can provide different templates for the login UI. These templates directories are set in the configuration, the default example being located in folder oidc-provider/templates/default.

This UI is just for authentication through OIDC : there is no registration endpoints and it's not a management UI !

Contributions and governance

This project is maintained by COOPGO, a french cooperative providing substainable and inclusive mobility platforms, and is part of the COOPGO Technical Platform in the process of being open sourced.

Feel free to contribute, submit a pull request, or get in touch with us to discuss the roadmap !

Licence

This project is under the AGPLv3 licence.

Alternatives

We try to be as generic as possible with this service and it could serve other purposes than just mobility use cases. This could probably be used in other scenarios by adapting default configurations.

However, you may also find "generic" (and probably more advanced feature wise) alternatives with :

• Ory Kratos with Ory Hydra (our OpenID Connect provider uses the Ory Fosite library from Hydra)
• Authboss
• Keycloak
• ...