Documize Export

Documize Export

Thu Apr 15 19:38:41 2021
1. Advanced Settings2. Application Setup Guides3. Configuration Options4. Getting Started with CoreID5. IAM Policy6. Installation
Advanced Settings
Information about the various advanced settings which can be managed by super-users through the Settings interface on the sidebar.

The advanced settings are runtime settings that customize the way CoreID functions. These settings have functional defaults, so change them at your own risk.

The settings are managed by super-users in the Settings page. The key is a string specifying the setting, and the value is the JSON string encoding the value. This might be an array, object, or raw value.

 

These settings deal with various aspects of the user registration process.

auth.allow_registration (default true)

This is a true/false value. If true, users are allowed to self-register. If false, the registration button and form are disabled.

auth.default_roles (default ["base_user"])

This is an array of strings. The strings in the array are a list of roles that are given to newly registered users. The base_user setting should always be present, as it allows the user to sign into the CoreID dashboard and manage their password settings.

Additional roles that can be included:

These settings deal with the public-facing homepage.

home.allow_landing (default true)

If false, the home/landing page will not be shown. Instead, users will be redirected to the dashboard.

home.redirect_authenticated (default true)

If true, authenticated users who browse to the home/landing page will be redirected to the dashboard.

Application Setup Guides
A collection of guides on how to setup various applications to authenticate users using CoreID.

Nextcloud is a self-hosted private cloud solution that, throught first- and third-party extensions, can provide file sync, calendar, contacts, task tracking, photos sync, and more. Because of its rich plugin ecosystem, Nextcloud supports a wide variety of authentication backends.

For our purposes, we'll be configuring Nextcloud to authenticate using SAML2, and setting up LDAP. The LDAP is necessary because the SAML2 plugin for Nextcloud requires the user information to be looked up from a different backend source. So, users will sign-in with SAML2 (meaning they see the familiar CoreID login flow), but Nextcloud will look up their information using LDAP.

 

Part 1: LDAP Setup

The first thing we need to do is create an LDAP authentication client and an application for our Nextcloud install in the CoreID dashboard. To do this, sign-in to CoreID as a super-user and take the following steps:

  1. Navigate to the Applications interface and click the Setup Wizard button.
  2. Using the setup wizard, fill in the name and identifier of your Nextcloud app. These can be anything you want, but the name will be shown to users so it's best to make it something sensible.
  3. For the authentication type, choose "LDAP (BindDN or Simple)." You'll now be prompted to enter LDAP credentials. These are the credentials Nextcloud will use to look up users from the LDAP server.
  4. After doing that, you'll land on the success page of the setup wizard. Leave this page open, or note its contents, as we'll be using some of the values provided here to configure Nextcloud.

Now, log into your Nextcloud instance as a user with administrative permissions. Then, use the following steps to set up Nextcloud to use the CoreID LDAP backend:

  1. Click on your user icon in the top right, then click the "Apps" menu item. This will load the extensions interface.
  2. Using the search bar at the top of the page, locate the "LDAP user and group backend" extension and enable it.
    1. If the enable button is not available, make sure you have the php-ldap extension installed and enabled.
  3. Then, click your user icon in the top right, then click the "Settings" menu item.
  4. Navigate to the "LDAP / AD integration" settings page under the "Administration" section of the sidebar.

  5. On the "Server" tab, fill in the address of your CoreID instance, as well as its LDAP port. Then, enter the LDAP credentials you just created. The bind DN corresponds to the "Bind User DN" shown on the final page of the application setup wizard.

  6. Now, navigate to the "Expert" tab. Since CoreID provides only a basic LDAP server implementation, we need to fill in some values here.
  7. First, set the "Internal Username" field to "uid". This is what CoreID provides.
  8. Also, override the "UUID Attribute for Users" and "UUID Attribute for Groups" to "uid" and "cn" respectively.

  9. Navigate to the "Advanced" tab and expand the "Directory Settings" section. We'll fill in a few of these fields:


    1. User Display Name Field: gecos
    2. Base User Tree: ou=people,dc=example,dc=domain
      1. This corresponds to the "User search base" value displayed on the last page of the CoreID application setup wizard.
    3. Group Display Name Field: cn
    4. Base Group Tree: ou=groups,dc=example,dc=domain
      1. This corresponds to the "Group search base" value displayed on the last page of the CoreID application set wizard.
    5. Paging chunksize: 0
      1. This disables paging, which is not supported by CoreID
  10. Now, navigate to the "Users" tab. Click the "Edit LDAP Query" button and fill in the LDAP filter for the CoreID application.



    This query corresponds to the "Search filter" displayed on the last page of the CoreID application setup wizard, however you should remove the "(uid=username_substituted_here)" clause.
  11. Navigate to the "Login Attributes" tab and click the "Edit LDAP Query" button. Fill in the LDAP filter for the CoreID application.



    This query corresponds to the "Search filter" displayed on the last page of the CoreID application setup wizard, however you should replace the "username_substituted_here" with "%uid".

At this point, you have successfully set up your Nextcloud application to authenticate users via LDAP. After granting a user or group permission to access the application, you should be able to sign in with your CoreID username and password.

However, the downside here is that it isn't immediately obvious to users that they're signing in with CoreID. It would be better for the users to be redirected to the CoreID login page to sign in. To accomplish this, we'll set up SAML2 integration as well.

 

Part 2: SAML 2.0 Setup

To set up SAML integration with CoreID, we will need to use an extension to Nextcloud, and point it to our CoreID instance. First, we need to set up the SAML Service Provider in CoreID.

  1. Sign into your CoreID instance as a super-user and navigate to the "SAML Service Providers" interface.
  2. Fill in a name for your Nextcloud app. This can be anything, but it will be shown to users, so it's best to make is something sensible.
  3. For the rest of the fields, fill in the following. (Replace nextcloud.example.domain with the address of your Nextcloud server.


    1. Entity ID: http://nextcloud.example.domain/index.php/apps/user_saml/saml/metadata
    2. Assertion Consumer Service URL: http://nextcloud.example.domain/index.php/apps/user_saml/saml/acs
  4. After saving the service provider, you'll see the Client ID and Client Secret. Keep the form open or note these down, as we'll need to fill these in later.
  5. Navigate to the Applications interface and click the edit button for the Nextcloud application we created earlier.
  6. In the form for the Nextcloud application, select the service provider we just created in the "" section and save the application.

This is the config we needed to do to link the SAML service to the LDAP client and the Nextcloud application in CoreID. Now, we need to set up the SAML login flow in Nextcloud itself.

  1. Sign into your Nextcloud instance as a user with administrative permissions.
  2. Click the user icon in the top right and click the "Apps" item. This will open the extensions interface.
  3. Using the search bar at the top of the page, locate the "SSO & SAML authentication" extension and enable it.
  4. Click the user icon in the top right and click the "Settings" item. Navigate to the "SSO & SAML authentication" menu item in the Administration section of the side bar.
  5. In the "Global settings" section, modify the checkboxes so that the SAML login is used for desktop clients, and only allows login if the user can be found in LDAP.

  6. In the "General" section, fill in the name and UID attribute for CoreID:



    For CoreID, the UID is mapped to the "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier" field. The name can be whatever you wish, but again this is shown to users.
  7. In the "Identity Provider Data" section, we need to tell Nextcloud how to authenticate users against our CoreID server.


    1. The Identifier of the IdP is the URL of the CoreID SAML metadata: https://coreid.example.domain/saml/metadata.xml
    2. The URL Target is the URL where Nextcloud will redirect users to be signed in: https://coreid.example.domain/saml/sso
    3. If you want, you can configure single-log out by filling in: https://coreid.example.domain/saml/logout
    4. You will need to fill in the public X.509 certificate for CoreID. This certificate was configured when you installed CoreID, and is the file referenced by the SAML_CERT_FILE configuration option.
  8. After saving these values, Nextcloud will be configured to perform SAML authentication against your CoreID instance.

You can test this out by signing out of your Nextcloud instance and navigating to the base URL. It should automatically redirect you to the CoreID login page.

If, for some reason, you need to bypass the CoreID login and sign in to Nextcloud directly, you can navigate to https://nextcloud.example.domain/index.php/login?direct=1.

Gitea is an awesome, self-hosted GitHub alternative. It also supports a reasonably large number of authentication backends. We'll look at two different ways you can set up your Gitea instance to authenticate against CoreID.

 

Option 1: LDAP

Gitea supports authenticating through CoreID's OpenLDAP-compatible server. Here's how to get it up and running:

  1. Sign in to your CoreID instance as a super-user, and navigate to Applications > Setup Wizard.
  2. Fill in an application name for your Gitea instance and a unique identifier. Then, click next.
  3. Choose "LDAP (BindDN or Simple)" from the list of authentication client types.
  4. Now, you'll need to create an LDAP username and password that Gitea can use to authenticate users:



  5. You'll land on a page listing out the various LDAP credentials and details that were just created:



  6. Now, we will configure Gitea to authenticate against CoreID. Sign-in to Gitea as an administrator, then navigate to the user menu > Site Administration > Authentication Sources.
  7. Click "Add Authentication Source"



  8. Fill in the following values on the form:
    1. Authentication Type: LDAP (via BindDN)
    2. Authentication Name: Starship CoreID
    3. Security Protocol: Unencrypted
    4. Host: your CoreID host address (e.g. coreid.example.domain)
    5. Port: 389
    6. Bind DN: the "Bind User DN" displayed in the Application Setup Wizard
      1. This is usually the LDAP username you created, in the users base.
      2. e.g. "uid=gitea_auth_user,ou=people,dc=example,dc=domain"
    7. Bind Password: the password you just set
    8. User Search Base: the "User search base" displayed in the Application Setup Wizard
      1. This is usually the LDAP suffix you set up prefixed with the people OU
      2. e.g. "ou=people,dc=example,dc=domain"
    9. User Filter: "(&(objectClass=inetOrgPerson)(iamTarget=iamTargetValue)(uid=%s))"
      1. Replace "iamTargetValue" with the value of the "iamTarget" in displayed in the Application Setup Wizard



    10. Admin Filter
      1. If you have created a CoreID group to designate admin users, you can fill that group in here using the LDAP format.
      2. For example, "(&(memberof=cn=Administrators,ou=groups,dc=example,dc=domain))", where "Administrators" is the name of the CoreID group you created.
    11. Username Attribute: uid
    12. First Name Attribute: cn
    13. Surname Attribute: sn
    14. Email Attribute: mail
    15. Uncheck "Use Paged Search" and "Fetch Attributes in Bind DN Context"

 

Option 2: OpenID Connect

Gitea also supports authenticating users via OpenID Connect. This has the added benefit of redirecting users to the common CoreID login page, which is a better overall experience. Here's how to set it up.

  1. First, open the CoreID Dashboard as a super-user, and navigate to the OpenID Connect Clients interface.
  2. Create a new client. Fill in the fields:
    1. Client Name: Gitea
    2. Redirect URI: https://gitea.example.domain/user/oauth2/Starship CoreID/callback
      1. Replace gitea.example.domain with the address of your Gitea instance.
    3. Grant Types: both "Refresh Token" and "Authorization Code"
  3. Once you create the OpenID Connect Client, you should be able to view the client ID and secret. Note these down temporarily.

  4. Now, navigate to the Applications interface. Create a new application using the "Manual Setup" button. Fill in:
    1. Name: Gitea
    2. Identifier: gitea
    3. : choose Gitea from the list
  5. Now that you've added the authentication client and application to CoreID, log into your Gitea instance as an administrator and navigate to the user menu > Site Administration > Authentication Sources and click "Add Authentication Source."
  6. Fill in the following values for the form:
    1. Authentication Type: OAuth2
    2. Authentication Name: Starship CoreID
    3. OAuth2 Provider: OpenID Connect
    4. Client ID (Key): the Client ID displayed in the CoreID form that we noted earlier
    5. Client Secret: the Client Secret displayed in the CoreID form that we noted earlier
    6. OpenID Connect Auto Discovery URL: https://coreid.example.domain/oidc/.well-known/openid-configuration
      1. Replace "coreid.example.domain" with the URL of your CoreID installation

 

 

After saving the authentication source, you should now see a "Sign-In with OpenID Connect (Starship CoreID)" button on the login page.

Flitter is my Node.js framework upon which, among other things, CoreID itself is built. Flitter-Auth provides a flexible connector for OAuth2 login, so it integrates well with CoreID.

We'll walk through setting up a Flitter-Auth provider to authenticate users against a CoreID instance. If your Flitter application hasn't already deployed Flitter-Auth, you'll want to do that first. You can find more info on that here.

 

CoreID Setup

Before we can configure your Flitter application, we need to create a CoreID application entry for it. This will generate the client ID and secret necessary for OAuth2 login.

  1. Sign in to your CoreID instance as a super-user and navigate to the Applications interface.
  2. Using the Setup Wizard, create a new OAuth2 application.
    1. For the OAuth2 callback URL, fill in https://your.flitter.app/auth/coreid/login
    2. This is where the user will be redirected after they've been authenticated with CoreID.
  3. After completing the wizard, you will land on the final page which shows information about the OAuth2 client just created. Note down the client ID and secret, as we'll need these in a moment.

Application Setup

Now that we've done the CoreID configuration, we will add CoreID as an authentication provider to your Flitter application. To do this, edit the config/auth.config.js file, and add a new entry to the "sources" object. Here's an example:

coreid: {
    type: 'Oauth2Provider',
    enable: env('AUTH_COREID_ENABLE', false),

    source_name: env('AUTH_COREID_SOURCE_NAME', 'Starship CoreID'),
    source_client_id: env('AUTH_COREID_CLIENT_ID'),
    source_client_secret: env('AUTH_COREID_CLIENT_SECRET'),
    source_login_page: env('AUTH_COREID_LOGIN_REDIRECT', 'https://coreid.example.domain/auth/service/oauth2/authorize?client_id=%c&redirect_uri=%r'),

    callback: {
        token_key: 'code',
    },

    source_token: {
        endpoint: 'https://coreid.example.domain/auth/service/oauth2/redeem',
        token_key: 'code',
        client_id_key: 'client_id',
        client_secret_key: 'client_secret',
        grant_type_key: 'grant_type',
        response_token_key: 'access_token',
    },

    user_data: {
        endpoint: 'https://coreid.example.domain/api/v1/auth/users/me',
        method: 'get',
        data_root: 'data',
        attributes: {
            uid: 'username',
            first_name: 'first_name',
            last_name: 'last_name',
        },
    },
}

For this config, the only things you should need to change is the domain of the CoreID server (and the source name, if desired). The rest of the configuration happens in the environment file for your Flitter app, where you will need to define the following environment variables:

Once this is complete, you should be able to navigate to https://your.flitter.app/auth/coreid/login, and you will be prompted to sign in with CoreID.

Firefly III is an open-source personal finance manager built on Laravel. It provides support for authenticating users over LDAP using the Adldap2 library for Laravel. An unfortunate side-effect of this integration is that we can't directly specify LDAP filters to be used for login.

So, we get a better-than-nothing solution here. Users from CoreID can sign in to Firefly III, but ANY user can sign in, regardless of IAM policy.

CoreID Setup

 

Configuration Options
A detailed overview of the environment configuration options available in CoreID.

Starship CoreID provides a rich set of configuration options that can be used to get the application up and running, and even customize some of its inner workings.

These settings can be customized by adding them to the .env file in the root of your CoreID installation.

APP_NAME (default Starship CoreID)

This is the name of the application as it appears in any user interfaces.

APP_URL (default http://localhost:8000/)

The fully-qualified URL to your application. This is used internally for building URLs. It should end with a slash.

APP_DEFAULT_LOCALE (default en_US)

The locale to default new sessions to. This is currently English, as that is the only supported Locale at the moment.

CoreID requires access to a MongoDB instance.

DATABASE_NAME (default coreid)

The MongoDB database name to use.

DATABASE_HOST (default localhost)

The hostname or IP address of the MongoDB server.

DATABASE_PORT (default 27017)

The port of the MongoDB server on the host.

DATABASE_AUTH (default false)

If true, CoreID will authenticate against the MongoDB instance using the username and password. If this is enabled, the DATABASE_USERNAME and DATABASE_PASSWORD options are required.

DATABASE_USERNAME

If DATABASE_AUTH is true, the username to authenticate with.

DATABASE_PASSWORD

If DATABASE_AUTH is true, the password to authenticate with.

REDIS_HOST (default localhost)

The hostname or IP address of the Redis server.

REDIS_PORT (default 6379)

The port of the Redis server on the host.

SERVER_PORT (default 80)

The port on the host that the CoreID web server should listen on.

ENVIRONMENT (default production)

The type of environment that CoreID is running in. Should be either production or development. Setting this to development will cause errors encountered during the request cycle to be rendered to the client. This is useful for debugging, but might pose security risks.

LOGGING_LEVEL (default 2)

The logging output level. By default, this is errors, success messages, and warnings. The available levels are:

LOGGING_TIMESTAMP (default false)

Include the timestamp in logging output if true.

SECRET (default changeme)

The randomly generated secret used for cryptographic purposes w/in the application. This should be set to a randomly generated UUID. For example:

node -e "console.log(require('uuid').v4())"

SSL_ENABLE (default false)

If true, CoreID’s web server will expect connections over HTTPS. If this is true, the SSL_CERT_FILE and SSL_KEY_FILE options are required.

SSL_CERT_FILE (default cert.pem)

The path to the SSL certificate public file.

SSL_KEY_FILE (default cert.key)

The path to the SSL certificate key file.

CoreID uses SMTP to send notification and password reset e-mails.

SMTP_HOST (default localhost)

The hostname or IP address of the SMTP server.

SMTP_PORT (default 587)

The port of the SMTP server on the host.

SMTP_SECURE (default false)

If true, connect to the SMTP server using TLS or STARTTLS.

SMTP_DEFAULT_SENDER

The e-mail address to use as the From line. In almost all cases, this should be the same as the SMTP_USER.

SMTP_USER

The username of the SMTP user used to send mail.

SMTP_PASS

The password of the SMTP user used to send mail.

CoreID uses Flitter’s first-party authentication provider, flitter-auth on the backend. While most of its functionality is configurable, it’s not recommended that you modify it, as certain parts of CoreID rely on assumptions about the flitter-auth configuration. However, there are a few settings that might be helpful:

MFA_SECRET_LENGTH (default 20)

The length of the randomly-generated secret used when user’s set up TOTP-based multi-factor authentication.

OAUTH2_SERVER_ENABLE (default true)

If false, the OAuth2 login server will be disabled, and OAuth2 applications will no longer be able to authenticate against CoreID.

AUTH_MIN_PASSWORD_LENGTH (default 8)

The minimum required password length for the user. (Note that CoreID imposes additional complexity requirements.)

SAML_PROVIDER_NAME (default http://localhost:8000/saml/metadata.xml)

The fully-qualified URL to the SAML metadata file to be included in the metadata itself. Yes, this is kind of circular. CoreID provides auto-generated metadata at the /saml/metadata.xml endpoint, however because of eccentricities that arise when self-hosting CoreID behind a reverse-proxy, it’s necessary to manually specify this value.

If the address that services would actually use to access your CoreID server is https://coreid.mydomain.com, then this value should be https://coreid.mydomain.com/saml/metadata.xml.

SAML_CERT_FILE

The fully-qualified path to the X.509 certificate file.

SAML_KEY_FILE

The fully-qualified path to the X.509 certificate key file.

SAML_SLO_LOGOUT_ENDS_COREID_SESSION (default true)

If true, then a SAML single-log-out request will also end the CoreID session. Setting this to false means that a user can log out of a service provider, but not be logged out of CoreID.

CoreID has a built-in OpenLDAP-compatible server. You can customize the server and its formats using the following options:

LDAP_SERVER_PORT (default 389)

This changes the port that the CoreID LDAP server will bind to. If the port is below 1000, you’ll need to give Node.js permission to bind to that port.

LDAP_MAX_CONNECTIONS

By default, there is no limit. However, you can override this to limit the number of concurrent connections to the CoreID LDAP server.

LDAP_LISTEN_INTERFACE (default 0.0.0.0)

The network interface on which the LDAP server should listen. By default, this is any interface.

LDAP_BASE_DC (default dc=example,dc=com)

This is the base DC that will be used for the LDAP server. It will be the suffix of all users and groups as they appear to LDAP-facing applications. It’s suggested that you change this to match your application’s domain.

LDAP_AUTH_BASE (default ou=people)

The LDAP prefix used for authenticatable users. So, by default, an example user would be uid=username,ou=people,dc=example,dc=com.

LDAP_GROUP_BASE (default ou=groups)

The LDAP prefix used for groups. By default, an example group would be cn=Some Group,ou=groups,dc=example,dc=com.

OPENID_CONNECT_PROXY (default false)

Set this to true if your CoreID instance is behind a proxy. This tells the OpenID Connect provider to trust the proxy headers. Use this setting if your OpenID Connect configuration is using the wrong protocol/URL.

Getting Started with CoreID
Initial setup and a quick walk-through of your new CoreID installation.

This guide assumes you have just completed the Installation instructions and have a brand-new CoreID instance. We’ll walk through getting the initial administrator user set-up, and talk through some of the basic concepts of the interface.

The first user to register with a new CoreID instance automatically becomes the super-user. The super-user is able to manage internal aspects of the CoreID setup, such as system settings, authentication clients, and access management. Any additional users registered after the first user are registered as standard users.

To create the super-user, navigate to the homepage for your CoreID installation and click the "Dashboard" button.

 

 

This will take you to the login page, where you should click the "Need an account?" button to register a new user.

 

 

Once you do, you'll be taken to the registration page, which will walk you through creating a new user and setting the password for the first time. After setting your password, you'll be prompted to sign in using your newly-created username and password.

Sign-in, and you'll be greeted with the CoreID dashboard:

 

 

The first page you see is your profile. You can use this to change basic aspects about your user, reset your password, and/or enable multi-factor authentication. Next, we'll walk through some of the basic concepts in CoreID.

CoreID is organized into several layers of abstractions. These abstractions allow you to integrate all types of applications as service providers and manage them in a consistent fashion. We’ll cover some of those abstractions now.

This is perhaps the most standard aspect of CoreID. The system has many users who can sign-in to the CoreID dashboard and manage their password, profile, and MFA settings. Depending on whether or not you configure it, these users can self-register, or you can manage their accounts manually via the Users tab on the left sidebar of the dashboard:

 

 

Each user can be organized into one or more groups. These groups allow you to apply permissions and access to users en masse, but otherwise don't affect the user's account. These groups are not visible to the user. You can manage them using the Groups tab on the left side of the dashboard:

 

 

You can assign users to a particular group by creating or editing that group and using the multi-select field to choose the users which should be members of that group. Users can belong to more than one group.

 

 

Information about user groups is made available to the applications which integrate with CoreID via whatever medium the protocol supports. For example, when authenticating over LDAP, the user's groups are made available as the memberOf overlay. In OAuth2, they can be accessed via the API.

Authentication clients are the various applications and services that integrate with CoreID and use it to authenticate users. The goal of CoreID is to provide as many different protocols as possible so that CoreID can be integrated with whatever applications you use in your environment. Currently, the following authentication protocols are supported by CoreID:

So, if your application provides a way for users to sign-in using any of the above protocols, it can be integrated with CoreID. In CoreID, authentication clients are distinct from the concept of "Applications," as a single application may need multiple authentication sources (e.g. Nextcloud requires LDAP for SAML to work properly). Thus, auth sources are managed separate to applications.

We'll cover the four types of auth sources in more detail.

LDAP clients are authentication sources that use an LDAP connection to authenticate users, whether that's by BindDN, or classic lookup. CoreID provides an integrated LDAP server that is compatible with the most common subsets of the OpenLDAP protocol.

The application setup wizard can help you configure an LDAP client, but they can be managed directly using the LDAP Clients interface:

 

 

One thing to note is that when you create an LDAP client, it will create a placeholder user account for that client:

 

 

This is normal. CoreID uses the placeholder user accounts to authenticate LDAP clients in a similar fashion to how users authenticate. These placeholder LDAP clients cannot sign into CoreID directly.

OAuth2 clients are authentication sources that use the OAuth2 protocol to authenticate users and retrieve a bearer token. This token can then be used to request user data from the CoreID API.

The application setup wizard can help you configure an OAuth2 client, but if you need to manage them manually, you can do so via the OAuth2 Clients interface:

 

 

When creating an OAuth2 client manually, you have the option to select the API scopes this client will have access to. By default, the "v1:api:users:get" and "v1:api:groups:get" should be sufficient for most applications which need to authenticate over this protocol.

However, there are many other API scopes listed there because it is possible to give an OAuth2 client access to the full CoreID API. While this isn't necessary in most cases, it provides a method for programmatically managing, and even automating CoreID.

You can select scopes in the form for the OAuth2 client. Once you've saved the client, you'll also be able to view their client ID and client secret from this form:

 

 

For testing or automation purposes, you can programmatically generate API tokens for a client for your user without having to sign in with that client's application. To do this, click your user menu in the top right corner and navigate to "API Tokens."

 

 

From this interface, you can generate new OAuth2 bearer tokens for a given client. This means that the token will authenticate your user in the context of the client you select. So, the bearer token will have your user's permissions and access to only the API scopes you selected for the client:

 

 

API bearer tokens generated this way are valid for 1 week.

OpenID Connect is a special protocol built on OAuth2 which is used for authentication. Unlike OAuth2, OpenID Connect has strict definitions for the various API endpoints and response formats. This means that any OpenID Connect-compatible client can talk to any OpenID Connect-compatible server.

CoreID provides an OpenID Connect-compatible server available at the "/oidc" endpoint. You can manage OpenID Connect clients using the OpenID Connect Clients interface:

 

 

From this interface, you can create OpenID Connect clients, and select the grant types available to those clients. For most clients, you want to select both the "Refresh Token" grant type, and the "Authorization Code" grant type. You can do this from the form for a client. Similar to an OAuth2 client, once you save the form you can view the client's client ID and client secret.

 

SAML, or Security Assertion Markup Language, is an authentication protocol that exists sort of as the precursor to OAuth2. It's common in many enterprise-type applications, and is still quite common. It's preferred to LDAP because SAML allows the user to be redirected to a common login page.

CoreID provides an integrated SAML 2.0-compatible server. The application setup wizard can help you setup SAML 2.0 Service Providers, but if you need to manage them directly, you can do so using the SAML Service Providers interface.

 

In CoreID, an application is a collection of one or more authentication clients that are managed together. Most applications use only one authentication client, however some may use multiple. Keeping applications separate from their authentication clients means we can manage users' access to an application in a common manner, regardless of what authentication protocol the application uses.

Using IAM Policy, which we'll cover in a moment, users and groups can be granted or denied access to an application. Applications can be managed using the Applications interface:

 

 

There are two ways to set up an application with CoreID. If you have manually created the authentication clients for the application, you can use the manual setup form to create an application and associate it with those existing authentication clients:

 

 

In this example, we create an application called "Example Manual App" that is associated with the "Example LDAP Client" and "Example SAML2 SP" authentication clients.

Alternatively, if you haven't added the authentication clients for the application yet, you can use the application setup wizard. This wizard will walk you through creating an authentication client first, then creating the application. Once you've done this, the wizard will provide you with some information on setting up the authentication client for that application:

 

IAM stands for Identity an Access Management. In CoreID, IAM Policy controls which users and groups can access which resources and applications managed by CoreID. This is the proverbial meat and potatoes of how you grant users access to the applications you manage.

IAM Policy is managed through the IAM Policy interface on the sidebar.

 

 

By default, if a user tries to access a resource with no policy governing it, they are denied access by default. Therefore, you must create IAM policy allowing users to access resources. We have a separate guide on managing IAM Policy, but here's a quick example. We'll grant the Admins group access to an example application:

 

 

Hopefully, this guide helped clarify the basic structure and usage of Starship CoreID. The CoreID section of my wiki contains additional documentation and guides for CoreID describing various settings and aspects of CoreID, as well as setup guides for popular applications.

CoreID is developed over on my Git server, here.

IAM Policy
A slightly more detailed run-through of CoreID's IAM policy engine.

Identity and Access Management Policy defines what resources users and groups are (or are not) allowed to access. It is defined by super-users in the IAM Policy interface in the dashboard.

 

An IAM policy has three major parts: the subject, the access type, and the target. We'll run through each.

 

Subject

The subject of a policy is the actor to which the policy applies. Currently, there are two types of subjects in CoreID: users and groups.

If a policy is applied to a group, it is applied to every user in that group.

 

Access Type

The access type can be either "allow" or "deny." Allow policies grant users access to a resource, and deny policies prohibit their access to that resource.

 

Target

The target is the resource which the user is attempting to access. In CoreID, there are two types of targets: applications, and API scopes.

Application targets are the various applications you've created in CoreID's Applications interface. Allowing or denying access to an application either enables or disables the subject's ability to sign-in to that resource.

API scope targets are the various API scopes provided by the CoreID API itself. Allowing or denying access to an API scope either enables or disables the subject's ability to make requests to API endpoints managed by that scope. This can be useful if you want to allow a particular user to programmatically manage some resource within CoreID, such as LDAP clients. See the API documentation for more details.

 

Example

 

This policy will allow any user in the Admins group to sign into the "Example Wizard App" application.

When determining whether or not a subject can access a given target, the policy engine consults the IAM policies you have created. If there are multiple policies governing a particular subject, there are some rules in place to resolve these conflicts:

This manages how users are able to access various resources. But what does this look like?

 

OAuth2/OpenID Connect/SAML Applications

IAM policy is checked any time the user is redirected from an application to CoreID to be authenticated. If the user is denied access, then they are presented with an access denial message, and are never redirected back to the original application.

Because they are never redirected back, the authentication credentials for that given application are never generated (a bearer token for OAuth2 and OpenID Connect, and user data for SAML applications), so to the target application, it appears as if the user never finished signing-in.

 

LDAP Applications

For LDAP applications, the story is a bit more complicated. Because many LDAP applications authenticate a user by attempting to bind to the LDAP server as that user, there's not necessarily any way to differentiate between LDAP applications as applications.

To get around this, when you set up an application with an LDAP authentication client, CoreID asks that you add a special synthetic filter to the application authenticating users via LDAP. This filter checks a synthetic field on the user object called the "iamTarget". When this filter is passed along to the CoreID server, it tells CoreID which application the LDAP request came from.

As such, the IAM policy engine can apply its rules. If the user doesn't have access to the application, they will (1) not appear in the search results, and (2) not be allowed to bind to the LDAP server.

An example of the user filter might look something like this:

(&(objectClass=inetOrgPerson)(uid=some_username_here)(iamTarget=5asfb8dfiujosd3))

 

API Scopes

If a user tries to access an API endpoint for which IAM policy has denied them access, they will receive a 401 response.

Installation
Comprehensive guide on getting CoreID set up on your infrastructure.

CoreID is a Node.js application built on Flitter. It provides a centralized way to manage identity and access management for all your self-hosted applications using its built-in LDAP, SAML, OAuth2, and OpenID Connect services.

CoreID is a comprehensive auth solution, complete with MFA/e-mail notifications and other deferred jobs. As such, its installation requires a service to run the web front end, and a service to run the job queue processor. For the stack itself, the following is required:

You’ll also need a port for the web interface to run on (usually port 80, or 443), and a port for the LDAP server to run on (usually 389). The process of installing these tools is beyond the scope of this document, however there are plenty of resources available online.

Before we install the application itself, we’re going to create a non-privileged user to run CoreID. This is generally good practice when setting up production applications, as it can help mitigate potential attack vectors.

For the purposes of this tutorial, our system user will have a username of coreid.

useradd --system --create-home coreid

This will create a new user called coreid and will create a default home directory for that user, /home/coreid. We can become that user:

su - coreid

The rest of this tutorial, unless otherwise specified, should be executed as the coreid user, from that user’s home directory.

CoreID provides a built-in SAML2.0 server, which requires an X.509 certificate to verify the integrity of the sender, receiver. So, we need to generate an X.509 certificate for CoreID to use. Luckily, self-signed certificates are fine for this:

mkdir ~/x509
cd ~/x509

# Generate the certificate private key. You will be prompted for a passphrase:
openssl genrsa -aes128 -out coreid.key 2048

# Convert the key to RSA plaintext:
openssl rsa -in coreid.key -out coreid.key

# Create a new certificate signing request for the given key, for 720 days.
# This will prompt for information, which you should fill in. Importantly, you MUST NOT
# set a passphrase for this step if prompted.
openssl req -new -days 720 -key coreid.key -out coreid.csr

# Use the CSR to create a new X.509 certificate:
openssl x509 -in coreid.csr -out coreid.crt -req -signkey coreid.key -days 720

Now, you have an X.509 certificate and key to use with CoreID.

Now that we’ve created a run user, we can grab a copy of the CoreID application. This is done by cloning the latest version from the Git repository where CoreID is developed. Like so:

cd ~
git clone https://code.garrettmills.dev/Starship/CoreID coreid

If you don’t want to use git to clone the code, you can download a ZIP file of it here. Just extract that ZIP file to the same directory.

Now that we’ve got the code, we need to install the Node dependencies that it relies on. We will do that using the Yarn package manager:

cd ~/coreid
yarn install

After some resolving, linking, and installing, you should have the packages installed. Now, we need to create a file with the environment configuration for your install. This file tells CoreID how to deal with things like the database, Redis, and the SMTP server.

First, start by copying the example environment config and modifying it to fit your environment. Here’s a sample configuration file:

APP_NAME="Starship CoreID"
APP_URL=http://coreid.domain.tld/

SERVER_PORT=8000
LOGGING_LEVEL=2
LOGGING_TIMESTAMP=false

DATABASE_HOST=localhost
DATABASE_PORT=27017
DATABASE_NAME=coreid
DATABASE_AUTH=true
DATABASE_USERNAME=coreid
DATABASE_PASSWORD="something-secure"

SECRET="replace-me"
ENVIRONMENT=production

SSL_ENABLE=false
# SSL_CERT_FILE=cert.crt
# SSL_KEY_FILE=cert.key

LDAP_SERVER_PORT=389

# Every LDAP DN is suffixed with this automatically
LDAP_BASE_DC="dc=domain,dc=tld"

SAML_CERT_FILE="/home/coreid/x509/coreid.crt"
SAML_KEY_FILE="/home/coreid/x509/coreid.key"
SAML_PROVIDER_NAME="http://coreid.domain.tld/saml/metadata.xml"

REDIS_HOST=localhost
REDIS_PORT=6379

SMTP_HOST="mail.domain.tld"
SMTP_PORT="587"
SMTP_USER="coreid@domain.tld"
SMTP_DEFAULT_SENDER="coreid@domain.tld"
SMTP_PASS="something-secure"

This is just a brief overview of a typical configuration. For more information, see the docs for the full gambit of configuration options here.

Of particular note is the application secret. This is used for cryptographic purposes within CoreID, and should be set to a strong, randomly generated value. You can use CoreID to generate a random value to put here by running:

node -e "console.log(require('uuid').v4())"

CoreID provides a built-in LDAP server for compatibility with applications that only support SSO via OpenLDAP protocols. This server needs to bind to port 389. Because we’re running CoreID as a non-root user, we need to give Node permission to bind to port 389 since it’s in the protected range on most systems.

# run this command as root!
setcap CAP_NET_BIND_SERVICE=+eip "$(which node)"

This will give the Node.js executable permission to bind to port numbers under 1000.

Now, we should have all the dependencies and configuration in place to test launch CoreID to make sure it will launch correctly. Do this like so:

# run this command as coreid
cd ~/coreid
node flitter test

If CoreID is able to start correctly (and connect to the database, Redis, &c.), you should see a message like so:

 [SUCCESS] [TestDirective] Flitter launched successfully. That doesn't mean that all of your app logic works, just that the framework backend initialized properly.

Now that we have CoreID installed, we will set up a SystemD service file for the web interface. This will allow us to start and manage the CoreID service using SystemD, a common Linux process manager.

To do this, we will create a new service file for CoreID. Edit the file /etc/systemd/system/coreid-www.service using the text editor of your choice. Here’s a sample of the contents:

[Unit]
Description=The CoreID centralized identity server
After=syslog.target
After=network.target

[Service]
RestartSec=2s
Type=simple
User=coreid
Group=coreid
WorkingDirectory=/home/coreid/coreid/
ExecStart=/usr/bin/env node /home/coreid/coreid/index.js
Restart=always
Environment=USER=coreid HOME=/home/coreid/

[Install]
WantedBy=multi-user.target

This file tells SystemD that CoreID’s web interface can be started after the system logger, and network have initialized. It will run the CoreID server as the coreid user we created, and will restart it 2 seconds after it crashes.

Now, we can start the web interface:

# run this command as root!
systemctl daemon-reload
systemctl start coreid-www

Check the status using:

systemctl status coreid-www

At the bottom of the status message, you should see something to the effect of:

 [SUCCESS] [Server] Flitter running on port 8000! Press ^C to exit cleanly.

This means that the CoreID web interface is up and running! Enable the service to start on boot using:

systemctl enable coreid-www

CoreID relies on a separate worker instance running in the background to process certain intensive or time-consuming tasks like sending e-mail, or password resets.

This means we need to create a separate service to run the job queue in the background. To do this, we’re going to create a service file that is very similar to the one for the web interface. Edit the file /etc/systemd/system/coreid-jobs.service using the text editor of your choice. Here’s a sample of the contents:

[Unit]
Description=The CoreID job queue
After=syslog.target
After=network.target

[Service]
RestartSec=2s
Type=simple
User=coreid
Group=coreid
WorkingDirectory=/home/coreid/coreid/
ExecStart=/usr/bin/env node /home/coreid/coreid/flitter worker main
Restart=always
Environment=USER=coreid HOME=/home/coreid/

[Install]
WantedBy=multi-user.target

Now, start and enable the job queue like so:

# run these commands as root!
systemctl daemon-reload
systemctl start coreid-jobs

Check the status of the job queue:

systemctl status coreid-jobs

You should see an output that looks something like:

   [INFO] [WorkerDirective] Starting queue mailer...
   [INFO] [WorkerDirective] Starting queue password_resets...
   [INFO] [WorkerDirective] Starting queue notifications...

This means the CoreID job queue processor is running correctly. For most cases, a single job queue instance is enough, but you can technically run as many of these as necessary for high volume deployments.

You should now be able to navigate to the web interface on the port you configured in the environment file. If all goes well, you'll be greeted with the homepage for your new CoreID installation:

Now that you’ve got CoreID up and running, you can start setting up CoreID with your applications. Check out the Getting Started guide.