Repository files navigation

Ferrum is abetter Authorization Server, this is a Community version.

• Discord channel :https://discord.gg/9RYNYu2Mxq

Ferrum isOpenId-Connect Authorization server written on GO. It has Data Contract similar toKeycloak server (minimalKeycloak and we'll grow to full-fledgedKeyCloak analog).

Today we are havingfollowing features:

1. Issue new tokens.
2. Refresh tokens.
3. Control user sessions (token expiration).
4. Get UserInfo.
5. Token Introspect.
6. Managed from external code (Start andStop) making them anideal candidate for using inintegrationtests for WEB API services that usesKeycloak as authorization server;
7. Ability to use different data storage:
   • FILE data storage for small Read only systems
   • REDIS data storage for systems with large number of users and small response time;
8. Ability to use any user data and attributes (any valid JSON but with some requirements), if you have toproperly configure your users just add what user have todata.json or in memory
9. Ability tobecome high performance enterprise level Authorization server.

it hasendpoints SIMILAR toKeycloak, at present time we are having following:

1. Issue and Refresh tokens:POST ~/auth/realms/{realm}/protocol/openid-connect/token
2. Get UserInfoGET ~/auth/realms/{realm}/protocol/openid-connect/userinfo
3. Introspect tokensPOST ~/auth/realms/{realm}/protocol/openid-connect/token/introspect

Ferrum is thoroughly developing with maximal quality of code and solution; we are working using agit-flow approach; evenmaster branch is a stable release branch, butdevelop is also highly stable, therefore develop version could also be used in a production.

First of all build is simple rungo build from application root directory. Additionally it is possibleto generate self signed certificates - rungo generate from command line

If you don't specify the name of executable (by passing -o {execName} to go build) than name of executable = name of project

Run is simple (Ferrum starts with default config -config.json):

./Ferrum

To runFerrum with selected config i.e.config_w_redis.json :

./Ferrum--config ./config_w_redis.json

It is possible to start app in docker with already installedREDIS and with initial data (see pythondata insert script):

    docker-compose up--build

There are 2 ways to useFerrum:

1. Start with config file (described above)
2. Start with direct passconfig.AppConfig anddata.ServerData in application, i.e.

   app:=CreateAppWithData(appConfig,&testServerData,testKey)res,err:=app.Init()assert.True(t,res)assert.Nil(t,err)res,err=app.Start()assert.True(t,res)assert.Nil(t,err)// do what you should ...app.Stop()

At present moment we have 2 fully integration tests, and number of them continues to grow. To run test execute from cmd:

go test

For running Manager tests onRedis you must have redis on127.0.0.1:6379 withferrum_db /FeRRuM000authuser+passwordpair, it is possible to start docker_compose and test on composeferrum_db container

Configuration splitted onto several sections:

    ```json    "server": {        "schema": "https",        "address": "localhost",        "port": 8182,        "security": {            "key_file": "./certs/server.key",            "certificate_file": "./certs/server.crt"        }    }    ```  - data file: `realms`, `clients` and `users` application takes from this data file and stores in     app memory, data file name - `data.json`  - key file that is using for `JWT` tokens generation (`access_token` && `refresh_token`),     name `keyfile` (without extensions).

Users does not have any specific structure, you could add whatever you want, but for compatibilitywith keycloak and for ability to check password minimal user looks like:

{"info": {"sub":""// <-- THIS PROPERTY USED AS ID, PROBABLY WE SHOULD CHANGE THIS TO ID"preferred_username":"admin",// <-- THIS IS REQUIRED...    },"credentials": {"password":"1s2d3f4g90xs"// <-- TODAY WE STORE PASSWORDS AS OPENED    }}

in this minimal user example you could expandinfo structure as you want,credentials is a service structure,there are NO SENSES in modifying it.

Minimal full example of how to use coud be found inapplication_test.go, here is a minimal snippet:

vartestKey= []byte("qwerty1234567890")vartestServerData= data.ServerData{Realms: []data.Realm{{Name:"testrealm1",TokenExpiration:10,RefreshTokenExpiration:5,Clients: []data.Client{{Name:"testclient1",Type:data.Confidential,Auth: data.Authentication{Type:data.ClientIdAndSecrets,Value:"fb6Z4RsOadVycQoeQiN57xpu8w8wplYz"}},},Users: []interface{}{map[string]interface{}{"info":map[string]interface{}{"sub":"667ff6a7-3f6b-449b-a217-6fc5d9ac0723","name":"vano","preferred_username":"vano","given_name":"vano ivanov","family_name":"ivanov","email_verified":true},"credentials":map[string]interface{}{"password":"1234567890"}},}},},}varhttpsAppConfig= config.AppConfig{ServerCfg: config.ServerConfig{Schema:config.HTTPS,Address:"127.0.0.1",Port:8672,Security: config.SecurityConfig{KeyFile:"./certs/server.key",CertificateFile:"./certs/server.crt"}}}app:=CreateAppWithData(appConfig,&testServerData,testKey)res,err:=app.Init()iferr!=nil {// handle ERROR}res,err=app.Start()iferr!=nil {// handle ERROR}// do whatever you wantapp.Stop()

Since version0.9.1 it is possible to useCLI AdminSee

1. Run docker compose -docker compose up --build
2. List running containers -docker ps -a
3. Attach to running container using listed hashdocker exec -it 060cfb8dd84c sh
4. Run admin interface providing a valid configferrum-admin --config=config_docker_w_redis.json ..., see picture

Brief info about changes in releases.

Features:

• Keycloak compatible HTTP-endpoints to issue a newtoken and to getuserinfo

Features:

• documentation (readme.md file)
• integration tests

Features:

• fixed modules names

Features:

• changed module names to make it available to embedFerrum in an other applications

Features:

• Keycloak compatible HTTP-endpoint for token introspect

Features:

• removed/ therefore it is possible to interact withFerrum usinggo-cloak package

Features

• logging
• implemented token refresh
• better docs

Features:

• docker &&docker-compose for app running
• adminCLIAPI
• Redis as a production data storage

Features:

• admin cli added to docker
• test onRedis data manger
• used different config to run locally and in docker
• newerKeycloak versions support
• checked stability ifRedis is down,Ferrum does not crushes and wait untilRedis is ready
• swagger (-devmode option in cmd line) andKeycloak compatible HTTP endpointopenid-configuration
• support for federated user (without full providers impl, just preliminary)
• store password as a hashes