174 lines
7.4 KiB
Markdown
Executable File
174 lines
7.4 KiB
Markdown
Executable File
# COOPGO Mobility Accounts
|
|
|
|
COOPGO Mobility Accounts is a webservice handling profiles management on the COOPGO Technical Platform.
|
|
|
|
It supports the [CMS standard](https://github.com/fabmob/CMS) 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](https://github.com/ory/fosite) library
|
|
- Flexible account data models using JSON schemas to handle the [CMS standard](https://github.com/fabmob/CMS) 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 :
|
|
|
|
```yaml
|
|
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](https://github.com/fabmob/CMS) 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](https://etcd.io/) (see below for storage considerations)
|
|
|
|
## Storage options
|
|
|
|
### Accounts management
|
|
|
|
COOPGO Mobility Accounts supports the following databases for storage :
|
|
|
|
- [x] MongoDB
|
|
|
|
Feel free to contribute any other storage option.
|
|
|
|
### OpenID Connect provider
|
|
|
|
You need a running [Etcd v3](https://etcd.io/) 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](https://coopgo.fr), 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](https://github.com/ory/kratos) with [Ory Hydra](https://github.com/ory/hydra) (our OpenID Connect provider uses the [Ory Fosite](https://github.com/ory/fosite) library from Hydra)
|
|
- [Authboss](https://github.com/volatiletech/authboss)
|
|
- [Keycloak](https://www.keycloak.org/)
|
|
- ...
|