This repo contains the second iteration of the KBase authentication server.
UI endpoints are not versioned and not necessarily stable - behavior may change as needed to support the auth UI.
Note that the HTML UI supplied in this repo is a minimal implementation for the purposes of testing. In many cases a manual refresh of the page will be required to see changes. Further, once a checkbox is manually checked or unchecked that state will not change, even with a refresh - to see changes reset the form.
/
General server information including git commit, version, and server time.
/admin
Global admin tasks - force reset all passwords, revoke all tokens, view a token, search for users.
/admin/customroles
View, add, and delete custom roles.
/admin/config
View and edit the server configuration.
/admin/localaccount
Create a local account.
/admin/user/<user name>
View user, disable user, reset password, force password reset, and modify user roles.
/admin/user/<user name>/tokens
View and revoke tokens for a specific user.
/customroles
View custom roles. This page is publicly viewable to any user with a valid token.
/link
Link accounts.
/login
Login to a provider based account. Stores a cookie with a token.
/localaccount/login
Login to a local account. Stores a cookie with a token.
/localaccount/reset
Reset the password for a local account.
/logout
Logs the user out.
Removes the user's token from the database as well as any temporary link tokens associated with
the user. Removes the login, temporary login, and temporary link cookies except if JSON output
is requested, in which case it is expected that the UI manages the login token
(but not the temporary tokens).
/me
User page. Update name and email address, remove roles.
/tokens
List, create, and revoke tokens.
API endpoints are versioned and behavior should not change in a backwards incompatible manner without a change in version.
All API calls require a valid token in the Authorization
header except legacy API endpoints,
which continue to use their original protocol. All endpoints produce JSON data unless otherwise
noted.
Tokens are opaque strings - no particular structure should be assumed, and token string contents may change without notice.
GET /api/V2/me
See the current user's profile.
PUT /api/V2/me
Update the current user's email address and display name. Takes JSON encoded data with the
keys display
and email
.
GET /api/V2/users/?list=<comma separated user names>
Validate a set of user names and get the users' display names. Returns a map of username ->
display name. Any usernames that do not correspond to accounts will not be included in the map.
GET /api/V2/users/search/<prefix>/?fields=<comma separated fields>
Find users based on a prefix of the username or any parts of the display name, where parts are
delimited by whitespace. By default the search occurs on all fields; setting the fields query
parameter can restrict the search fields and thus possibly speed up the search. Current field names
are username
and displayname
; any other field names are ignored. Returns a map of
username -> display name. At most 10,000 names are returned.
GET /api/V2/token
Introspect a token.
POST /api/V2/token
Create an agent token. Takes JSON encoded data with the keys name
for a required token name
string and customcontext
for an optional map of user-supplied creation context to be saved
with the token, and returned when the token is queried.
Endpoints (mostly) identical to the original Globus and KBase auth endpoints are provided for backwards compatibility.
POST /api/legacy/KBase/Sessions/Login
The legacy KBase API.
GET /api/legacy/globus
The legacy globus API. Endpoints are /goauth/token and /users.
Test mode allows integration of the auth service into test harnesses for dependent services and applications by providing endpoints for creating test users, tokens, and roles on the fly. A subset of the API above is supported (see below).
To enable test mode, add the following line to the service deploy.cfg
file:
test-mode-enabled=true
Test mode should never be enabled for production services.
All test mode data is stored in separate collections from the standard data in the service data stores, and is automatically deleted one hour after creation. Test mode user accounts have no passwords and no linked identities and so logging into test mode accounts is impossible, although tokens can be created arbitrarily. Note that test mode user accounts are more or less arbitrarily specified as local accounts in the API.
Test mode data is only accessible via endpoints under the /testmode
root endpoint.
These endpoints mimic the behavior of the standard API endpoints above, but only interact with test mode data.
GET /testmode
GET /testmode/api/V2/me
GET /testmode/api/V2/token
GET /testmode/api/V2/users
POST /testmode/api/legacy/KBase/Sessions/Login
GET /testmode/api/legacy/globus
These endpoints allow a test harness to create and modify test mode users, tokens, and roles. No authentication is required.
POST /testmode/api/V2/testmodeonly/user
Create a user. Takes JSON encoded data with the keys user
for the user name and display
for
the user's display name.
GET /testmode/api/V2/testmodeonly/user/<username>
Get a user's data.
POST /testmode/api/V2/testmodeonly/token
Create a token. The user to which the token is assigned must exist. Takes JSON encoded data with
the keys user
for the user name, name
for an optional token name, and type
for the token
type. type
is one of Login
, Agent
, Dev
, or Serv
.
POST /testmode/api/V2/testmodeonly/customroles
Create a custom role. Takes JSON encoded data with the keys id
for the role id and desc
for
the role description. Posting a role with an existing ID overwrites the description of the role.
GET /testmode/api/V2/testmodeonly/customroles
Get the list of extant custom roles.
PUT /testmode/api/V2/testmodeonly/userroles
Set a user's roles, overwriting any current roles. Takes JSON encoded data with the keys user
for the user name of the user to modify, roles
for a list of built-in roles to grant to the
user, and customroles
for a list of custom role ids to grant to the user. Allowed roles
are
DevToken
, ServToken
, Admin
, and CreateAdmin
. Note that these roles don't grant
any actual privileges in test mode. Omitting roles
and customroles
removes all roles from
the user.
DELETE /testmode/api/V2/testmodeonly/clear
Removes all test mode data from the system.
-
It is expected that this server always runs behind a reverse proxy (such as nginx) that enforces https / TLS and as such the auth server is configured to allow cookies to be set over insecure connections.
-
If the reverse proxy rewrites paths for the auth server, cookie path rewriting must be enabled for the /login and /link paths. Nginx example:
location /auth/ { proxy_pass http://localhost:20002/; proxy_cookie_path /login /auth/login; proxy_cookie_path /link /auth/link; }
-
-
Get Globus creds here
- Required scopes are:
- urn:globus:auth:scope:auth.globus.org:view_identities
- Required scopes are:
-
Get Google OAuth2 creds here
-
Get OrcID creds here
- Note that only the public API has been tested with the auth server.
Java 8 (OpenJDK OK)
Apache Ant (http://ant.apache.org/)
MongoDB 2.6+ (https://www.mongodb.com/)
Jetty 9.3+ (http://www.eclipse.org/jetty/download.html)
(see jetty-config.md for version used for testing)
This repo (git clone https://github.com/kbase/auth2)
The jars repo (git clone https://github.com/kbase/jars)
The two repos above need to be in the same parent folder.
start mongodb
if using mongo auth, create a mongo user
cd into the auth2 repo
ant build
copy deploy.cfg.example
to deploy.cfg
and fill in appropriately
export KB_DEPLOYMENT_CONFIG=<path to deploy.cfg>
cd jettybase
./jettybase$ java -jar -Djetty.port=<port> <path to jetty install>/start.jar
Set a root password:
./manage_auth -d <path to deploy.cfg> -r
Login to a local account as ***ROOT***
with the password you set. Create a
local account and assign it the create administrator role. That account can
then be used to create further administrators (including itself) without
needing to login as root. The root account can then be disabled.
./jettybase$ java -DSTOP.PORT=8079 -DSTOP.KEY=foo -jar ~/jetty/jetty-distribution-9.3.11.v20160721/start.jar
./jettybase$ java -DSTOP.PORT=8079 -DSTOP.KEY=foo -jar ~/jetty/jetty-distribution-9.3.11.v20160721/start.jar --stop
Omit the stop key to have jetty generate one for you.
- Adding code
- All code additions and updates must be made as pull requests directed at the develop branch.
- All tests must pass and all new code must be covered by tests.
- All new code must be documented appropriately
- Javadoc
- General documentation if appropriate
- Release notes
- All code additions and updates must be made as pull requests directed at the develop branch.
- Releases
- The master branch is the stable branch. Releases are made from the develop branch to the master branch.
- Update the version as per the semantic version rules in
src/us/kbase/auth2/service/common/ServiceCommon.java
. - Tag the version in git and github.
- Copy
test.cfg.example
totest.cfg
and fill in the values appropriately.- If it works as is start buying lottery tickets immediately.
ant test
- Some fields are arbitrary text entered by a user. These fields should be HTML-escaped prior to
display. Currently the fields include:
- Custom role descriptions
- The reason for why a user account was enabled and disabled.
- User display names and email addresses.
- Token names
- Token custom context
Use common sense when displaying a field from the server regarding whether the field should be html escaped or not.
All the HTML templates for the test UI are in the /templates directory and are mustache templates.
In us.kbase.auth2.lib.exceptions
:
AuthException
and subclasses other than the below - 400
AuthenticationException
and subclasses - 401
UnauthorizedException
and subclasses - 403
NoDataException
and subclasses - 404
JsonMappingException
(from Jackson) - 400
Anything else is mapped to 500.