= Fabric8 Auth :toc: :toc-placement: preamble :sectnums: :experimental:
image:https://ci.centos.org/buildStatus/icon?job=devtools-fabric8-auth-build-master-push-client[Jenkins,link="https://ci.centos.org/job/devtools-fabric8-auth-build-master-push-client/lastBuild/"] image:https://goreportcard.com/badge/github.com/fabric8-services/fabric8-auth[Go Report Card, link="https://goreportcard.com/report/github.com/fabric8-services/fabric8-auth"] image:https://godoc.org/github.com/fabric8-services/fabric8-auth?status.png[GoDoc,link="https://godoc.org/github.com/fabric8-services/fabric8-auth"] image:https://codecov.io/gh/fabric8-services/fabric8-auth/branch/master/graph/badge.svg[Codecov.io,link="https://codecov.io/gh/fabric8-services/fabric8-auth"]
== Documentation [[docs]]
You can find both reference documentation and developer documentation in the following location:
link:https://fabric8-services.github.io/fabric8-auth/index.html[fabric8-auth docs].
== Building from source [[building]]
The following guide is mainly targeted towards a Linux or Mac OSX development machine. If you are on Windows, we recommend to take a look at link:docs/source/getting-started-win.adoc[Getting started with fabric8-auth development on Windows].
=== Prerequisites [[prerequisites]]
You need to install:
go (>= v1.8)gitmercurialmake==== Check your Go version [[check-go-version]]
Run the following command to find out your Go version.
You must at least have Go version 1.8.
See <
==== Install dep [[dep-setup]]
This project uses https://github.com/golang/dep[dep] as a package manager for Go.
Running the make deps command will install dep in $GOPATH/bin if it's not already available on your system.
=== Get the code [[get-the-code]]
Assuming you have Go installed and configured (have $GOPATH setup) here is
how to build.
Check out the code
=== Build [[build]]
Like most other projects, this one depends on various other projects that need to be downloaded.
We also generate some code from design files that shall make it into our final artifacts.
To fetch the dependencies, generate code and finally build the project you can
type make in a freshly clone repository of this project.
==== Special make targets
There is no need to fetch the dependencies, or re-generate code every time you
want to compile. That's why we offer special make targets for these topics:
===== Fetch dependencies [[fetch-dependencies]]
This will download all the dependencies for this project inside a directory
called vendor. This way we can ensure that every developer and our CI system
is using the same version.
For dependency management of go packages we use https://github.com/golang/dep[`dep`].
The file Gopkg.toml contains all dependencies. If you want to understand the format for this file, look link:https://golang.github.io/dep/docs/Gopkg.toml.html[here].
===== Generate GOA sources [[generate-code]]
You need to run this command if you just checked out the code and later if you've modified the designs.
===== Build [[build]]
If you want to just build the Auth server and client, run make build.
===== Clean [[clean]]
This removes all downloaded dependencies, all generated code and compiled artifacts.
===== Tests [[test]]
Here's how to run all available tests. All tests will check all Go packages
except those in the vendor/ directory.
Make sure you have docker and docker-compose available.
Setting up test environment - make integration-test-env-prepare
Tear test environment down - make integration-test-env-tear-down
docker-compose up -d db.
+docker-compose up -d db.
+By default, test data is removed from the database after each test, unless the AUTH_CLEAN_TEST_DATA environment variable is set to false. This can be particularily useful to run queries on the test data after a test failure, in order to understand why the result did not match the expectations.
Also, all SQL queries can be displayed in the output if the AUTH_ENABLE_DB_LOGS environment variable is set to `true. Beware that this can be very verbose, though ;)
===== Coverage [[coverage]]
To visualize the coverage of unit, integration, or all tests you can run these commands:
$ make coverage-unit$ make coverage-integration$ make coverage-allNOTE: If the tests (see <
Each of the above tests (see <
Here's how the
[horizontal]
<package>::
something like github.com/fabric8-services/fabric8-auth/models
<test>::
unit or integration
<mode>::
Sets the mode for coverage analysis for the packages being tested.
Possible values for <mode> are set (the default), count, or atomic and
they directly relate to the output of go test --help.
In addition to all individual coverage information for each package, we also create three more files:
[horizontal]
tmp/coverage.unit.mode-<mode>::
This file collects all the coverage profiles for all unit tests.
tmp/coverage.integration.mode-<mode>::
This file collects all the coverage profiles for all integration tests.
tmp/coverage.mode-<mode>::
This file is the merge result of the two afore mentioned files and thus gives
coverage information for all tests.
==== Development
These files and directories are generated and should not be edited:
./app/./client/./swagger/./tool/cli/== Developer setup
Start up dependent docker services using docker-compose and runs auto reload on source change tool fresh.
The above steps start the API Server on port 8089.
Test out the build by executing CLI commands in a different terminal.
NOTE: The CLI needs the API Server which was started on executing make dev to be up and running. Please do not kill the process. Alternatively if you haven't run make dev you could just start the server by running ./bin/auth.
You should get Token in response, save this token in your favourite editor as you need to use this token for POST API calls
=== Creating User using Service Account token in DB. ==== Creating Service Account token for online registration. We need Service Account token to create user in AUTH. Now to create SA token in development mode, we can use following api
curl -X POST http://localhost:8089/api/token -H 'Content-Type: application/json' -d '{
"client_id": "f867ec72-3171-4b8f-8eec-90a32eab6e0b",
"client_secret": "secret",
"grant_type": "client_credentials"
}'You will receive response like follow:
{"access_token":"eyJhbGciOiJSUzI1NiIsImtpZCI6IjlNTG5WaWFSa2hWajFHVDlrcFdVa3dISXdVRC13WmZVeFItM0Nwa0UtWHMiLCJ0eXAiOiJKV1QifQ.eyJpYXQiOjE1Mzg2NTYwMTYsImlzcyI6Imh0dHA6Ly9sb2NhbGhvc3QiLCJqdGkiOiI0MjA1NGE4MS1jNjdlLTQ0MGQtYjQ1My1kNzkwNmM3ZjE5MDQiLCJzY29wZXMiOlsidW1hX3Byb3RlY3Rpb24iXSwic2VydmljZV9hY2NvdW50bmFtZSI6Im9ubGluZS1yZWdpc3RyYXRpb24iLCJzdWIiOiJmODY3ZWM3Mi0zMTcxLTRiOGYtOGVlYy05MGEzMmVhYjZlMGIifQ.esAmoXFhkHq02-ABf22FHZtO7ytfNzmMHPoAYwsDYYVQ5thPyXPNTWXnhHu4bV0rACnf7R5oa3oIl14DhyPSTMjAN_qZZlWQC2qjhMEOBSbss_hW5BkYwU67YBhkHt_eYgfVuoAgi7SuMu5KucaBIMNBEpYrDXR6G9Q2qk3jq4tV4qbTaQ6P078pdfYKT2ue_eGbSEvUN4G33tTzI-TX6UrR3mi-jsavLkRGAPUZmvdIVigHMi-KM1oilw7IB24FB6rd4AMuD1OVhgV-r9qrA3MDdLP6mS_t09D30ROAoymJEy44OvbmdVo0XAQRD6_JyzHhK-YrAGN-39C5BDBeFw",
"token_type":"Bearer"
}==== Approving User in Auth DB and Creating user in WIT
Once you have RHD account and auth service running locally, you can use above created service account token to create user like following
curl -X POST http://localhost:8089/api/users -H "authorization: Bearer $SERVICE_ACCOUNT_TOKEN" -H 'content-type: application/json' -d '{
"data": {
"attributes": {
"email": "dipakpawar@gmail.com",
"rhd_username": "dipakpawar",
"username": "dipakpawar",
"cluster": "https://cluster-url.com",
"rhd_user_id":"3383826c-51e4-401b-9ccd-b898f7e2397d"
},
"type": "identities"
}
}'You don't have to find rhd_user_id from RHD as it is random UUID and you can put any random number there.
This will create identity and user in the auth DB and user in WIT. Make sure to give correct email and username with your identity provider(RHD).
Note: If you haven't not created user, you will get user dipakpawar is not approved error during logging. You need to follow above mentioned steps to approve user.
==== Running above steps using shell script If you are too lazy to do above steps just run following command with your server, username, email parameters.
curl -sSL https://git.io/fxY5T | bash -s -- -s http://localhost:8089/api/token -u username -e email -c mycluster.url.com=== Reset Database
The database are kept in a docker container that gets reused between restarts. Thus restarts will not clear out the database.
To clear out the database kill the database like this:
In case you have mulitple fabric8* running use docker ps to locate the container name.
== Rapid development on Minishift
See the following README in the minishift directory for instructions on running fabric8-auth in minishift:
link:minishift/README.md[Minishift README].