Keyrock

https://fiware-idm.readthedocs.io/en/latest
Admin
Keyrock is the FIWARE Identity Manager component that provides OAuth2-based authentication and...
Tokens:33,329
Snippets:150
Trust Score:8.3
Update:1 year ago
Show doc for...
Tokens:
Raw
### Launch FIWARE IDM Server

Source: https://fiware-idm.readthedocs.io/en/latest/installation_and_administration_guide/installation

Starts the FIWARE IDM Node.js server using the npm start command. Also includes instructions for installing and using forever.js for production environments.

```bash
npm start
```

```bash
sudo npm install forever -g
```

```bash
forever start bin/www
```

```bash
forever status
```

--------------------------------

### Host Installation of FIWARE Keyrock

Source: https://context7.com/context7/fiware-idm_readthedocs_io_en/llms.txt

Guides through installing Keyrock directly on a host system. This involves cloning the repository, installing Node.js dependencies, configuring the application via `config.js`, and initializing the database.

```bash
# Clone the repository
git clone https://github.com/ging/fiware-idm
cd fiware-idm

# Install dependencies
npm install

# Configure the application
cp config.js.template config.js

# Edit config.js with your settings:
# config.host = 'http://localhost:3000';
# config.port = 3000;
# config.database = {
#     host: 'localhost',
#     password: 'idm',
#     username: 'root',
#     database: 'idm',
#     dialect: 'mysql'
# };
# config.session = { secret: 'nodejs_idm' };
# config.password_encryption = { key: 'nodejs_idm' };

# Initialize database
npm run-script create_db
npm run-script migrate_db
npm run-script seed_db

# Start the server
npm start

# Or use forever for production
sudo npm install forever -g
forever start bin/www
forever status
```

--------------------------------

### Database Setup and Migrations for FIWARE IDM

Source: https://fiware-idm.readthedocs.io/en/latest/installation_and_administration_guide/installation

Executes npm scripts to create the database, run migrations, and seed the database with initial data for the FIWARE IDM.

```bash
npm run-script create_db
npm run-script migrate_db
npm run-script seed_db
```

--------------------------------

### Start Keyrock Server with Admin Rights

Source: https://fiware-idm.readthedocs.io/en/latest/installation_and_administration_guide/configuration

Command to start the Keyrock server, typically requiring administrator privileges (sudo) to bind to privileged ports like 443 for HTTPS.

```bash
sudo npm start
```

--------------------------------

### Deploy Keyrock Instance with Docker Compose

Source: https://fiware-idm.readthedocs.io/en/latest/getting_started

Defines the services and network configuration for deploying FIWARE IdM Keyrock and a MySQL database using Docker Compose. This YAML file specifies container images, ports, environment variables, and network settings for a local Keyrock deployment.

```yaml
version: '3.5'
services:
    keyrock:
        image: fiware/idm:7.8.1
        container_name: fiware-keyrock
        hostname: keyrock
        networks:
            default:
                ipv4_address: 172.18.1.5
        depends_on:
            - mysql-db
        ports:
            - '3000:3000'
            - '443:443'
        environment:
            - DEBUG=idm:*
            - IDM_DB_HOST=mysql-db
            - IDM_HOST=http://localhost:3000
            - IDM_PORT=3000
            - IDM_DB_PASS=secret
            - IDM_DB_USER=root
            - IDM_ADMIN_USER=admin
            - IDM_ADMIN_EMAIL=admin@test.com
            - IDM_ADMIN_PASS=1234

    mysql-db:
        restart: always
        image: mysql:5.7
        hostname: mysql-db
        container_name: db-mysql
        networks:
            default:
                ipv4_address: 172.18.1.6
        environment:
            - 'MYSQL_ROOT_PASSWORD=secret'
            - 'MYSQL_ROOT_HOST=172.18.1.5'
        volumes:
            - mysql-db:/var/lib/mysql

networks:
    default:
        ipam:
            config:
                - subnet: 172.18.1.0/24
volumes:
    mysql-db: ~
```

--------------------------------

### Clone FIWARE IDM Repository

Source: https://fiware-idm.readthedocs.io/en/latest/installation_and_administration_guide/installation

Clones the FIWARE Identity Manager (IDM) source code from GitHub. This is the initial step for host installation.

```bash
git clone https://github.com/ging/fiware-idm
```

--------------------------------

### Email Domain List Example

Source: https://fiware-idm.readthedocs.io/en/latest/installation_and_administration_guide/configuration

Example content for an email domain whitelist file. Each line specifies a valid email domain (without '@') allowed for registration in Keyrock.

```text
allow.com
valid.es
permit.com

```

--------------------------------

### Register Application with API Token using cURL

Source: https://fiware-idm.readthedocs.io/en/latest/getting_started

Registers a new application with Keyrock by sending a POST request. This request includes the previously obtained API token in the 'X-Auth-token' header and application details like name, description, and redirect URI in the JSON body. The response provides the application's ID and secret.

```shell
curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "X-Auth-token: <API-TOKEN>" \
     --data-binary "{
  \"application\": {
    \"name\": \"Test_application 1\",
    \"description\": \"description\",
    \"redirect_uri\": \"http://localhost/login\",
    \"url\": \"http://localhost\",
    \"grant_type\": [
      \"authorization_code\",
      \"implicit\",
      \"password\"
    ],
    \"token_types\": [
        \"jwt\",
        \"permanent\"
    ]
  }
}" \
'http://localhost:3000/v1/applications'
```

--------------------------------

### Obtain User Information with Access Token (cURL)

Source: https://fiware-idm.readthedocs.io/en/latest/getting_started

This snippet demonstrates how to use a cURL command to retrieve information about the user associated with a given access token. It requires the Keyrock service to be running locally on port 3000 and an active access token. The output is a JSON object containing user details.

```curl
curl "http://localhost:3000/user?access_token=cd8c8e41ab0db220315ed54f173087d281a4c686"
```

--------------------------------

### Install Node.js Dependencies with npm

Source: https://fiware-idm.readthedocs.io/en/latest/installation_and_administration_guide/installation

Installs all required Node.js libraries for the FIWARE IDM project using npm. This command should be run after cloning the repository.

```bash
cd fiware-idm
npm install
```

--------------------------------

### Run Keyrock in Debug Mode via Shell

Source: https://fiware-idm.readthedocs.io/en/latest/installation_and_administration_guide/configuration

Starts Keyrock in debug mode using an npm script. This command requires nodemon to be installed, which automatically restarts the server upon code changes.

```bash
npm run debug
```

--------------------------------

### Generate API Token with cURL

Source: https://fiware-idm.readthedocs.io/en/latest/getting_started

Generates an API token by making a POST request to the Keyrock authentication endpoint with default user credentials. The response contains the 'X-Subject-Token' header, which is the API token required for subsequent requests.

```shell
curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --data-binary "{
  \"name\": \"admin@test.com\",
  \"password\": \"1234\"
}" \
'http://localhost:3000/v1/auth/tokens'
```

--------------------------------

### Create Custom Translations Directory

Source: https://fiware-idm.readthedocs.io/en/latest/installation_and_administration_guide/configuration

Sets up a directory for custom translation files within a theme.

```bash
mkdir themes/example/translations

```

--------------------------------

### Create Custom Theme Directory

Source: https://fiware-idm.readthedocs.io/en/latest/installation_and_administration_guide/configuration

Creates a new directory for a custom theme within the themes folder.

```bash
mkdir themes/example

```

--------------------------------

### Create Custom Template Files

Source: https://fiware-idm.readthedocs.io/en/latest/installation_and_administration_guide/configuration

Generates EJS template files (_footer.ejs, _header.ejs, _presentation.ejs, _help_about_items.ejs) for customizing portal sections within a theme.

```bash
mkdir themes/example/templates
cd themes/example/templates && touch _footer.ejs _header.ejs _presentation.ejs _help_about_items.ejs

```

--------------------------------

### User Information Response Example

Source: https://fiware-idm.readthedocs.io/en/latest/oauth/oauth_documentation

An example JSON response detailing user information, including organizations, roles, display name, email, and application-specific details.

```JSON
{
  "organizations": [
    {
      "id": "13e88767-7473-472d-9c33-110c5bed2a57",
      "name": "test_org",
      "description": "my org",
      "website": null,
      "roles": [
        {
          "id": "9c4e8db4-a56b-4731-bfc6-7dd8fb2fbea3",
          "name": "test"
        }
      ]
    }
  ],
  "displayName": "My User",
  "roles": [
    {
      "id": "9c4e8db4-a56b-4731-bfc6-7dd8fb2fbea3",
      "name": "test"
    }
  ],
  "app_id": "ff03921a-a772-4220-9854-e2d499ae474a",
  "isGravatarEnabled": false,
  "email": "myuser@test.com",
  "id": "myuser",
  "authorization_decision": "",
  "app_azf_domain": "",
  "username": "myuser"
}
```

--------------------------------

### Create Custom Email Templates Directory

Source: https://fiware-idm.readthedocs.io/en/latest/installation_and_administration_guide/configuration

Establishes a directory for customizing email headers and footers within a theme.

```bash
mkdir themes/example/email
touch themes/example/email/_header.ejs
touch themes/example/email/_footer.ejs

```

--------------------------------

### Obtain OAuth Token with Resource Owner Password Credentials Flow using cURL

Source: https://fiware-idm.readthedocs.io/en/latest/getting_started

Obtains an OAuth token using the Resource Owner Password Credentials flow. It requires setting environment variables for the application ID and secret, then making a POST request with Basic Authentication and form-urlencoded data, including grant type, username, and password.

```shell
ID=a17bf9e3-628d-4000-8d25-37703975a528
SECRET=ac5df1fe-4caf-4ae6-9d21-60f3a9182887
curl -X POST -H "Authorization: Basic $(echo -n $ID:$SECRET | base64 -w 0)"   --header "Content-Type: application/x-www-form-urlencoded" -d "grant_type=password&username=admin@test.com&password=1234" http://localhost:3000/oauth2/token
```

--------------------------------

### Generate Theme SCSS Files

Source: https://fiware-idm.readthedocs.io/en/latest/installation_and_administration_guide/configuration

Creates the necessary SCSS files (_colors.scss, _styles.scss, style.scss) for a new custom theme.

```bash
cd themes/example && touch _colors.scss _styles.scss style.scss

```

--------------------------------

### Configure FIWARE IDM Application

Source: https://fiware-idm.readthedocs.io/en/latest/installation_and_administration_guide/installation

Copies the template configuration file to create a new configuration file and sets database, port, host, session, and password encryption parameters for the FIWARE IDM.

```bash
cp config.js.template config.js
```

```javascript
config.host = 'http://localhost:3000';
config.port = 3000;
```

```javascript
config.database = {
    host: 'localhost',
    password: 'idm',
    username: 'root',
    database: 'idm',
    dialect: 'mysql'
};
```

```javascript
config.session = {
    secret: 'nodejs_idm'
};
```

```javascript
config.password_encryption = {
    key: 'nodejs_idm'
};
```

--------------------------------

### Start Docker Compose Services

Source: https://context7.com/context7/fiware-idm_readthedocs_io_en/llms.txt

Command to initiate the Keyrock and MySQL services defined in the Docker Compose file. After execution, Keyrock can be accessed using the default admin credentials.

```bash
# Start the services
docker-compose up

# Default admin credentials:
# Email: admin@test.com
# Password: 1234
```

--------------------------------

### Configure Registration Redirect URL in config.js

Source: https://fiware-idm.readthedocs.io/en/latest/installation_and_administration_guide/configuration

Specifies the URL and path to redirect users after registration and activation. 'redirect' is the base URL, and 'extension' is the path.

```javascript
config.registration = {
    redirect: 'https://example.com',
    extension: '/?new_user=1'
};

```

--------------------------------

### Configure Site Theme in config.js

Source: https://fiware-idm.readthedocs.io/en/latest/installation_and_administration_guide/configuration

Sets the default theme for the Identity Manager portal. Can be switched between 'default', 'fiwarelab', or a custom theme.

```javascript
config.site = {
    title: 'Identity Manager',
    theme: 'default' // default/fiwarelab
};

```

--------------------------------

### Add Default and Custom Styles to style.scss

Source: https://fiware-idm.readthedocs.io/en/latest/installation_and_administration_guide/configuration

Imports default theme colors and styles, followed by custom theme overrides, into the main style.scss file for a theme.

```scss
/****************************** Default colors */
@import '../default/colors';

/****************************** Custom colors */
@import 'colors';

/****************************** Default styles */
@import '../default/styles_call';

/****************************** Custom styles */
@import 'styles';

```

--------------------------------

### Configure OIDC JWT Algorithm

Source: https://fiware-idm.readthedocs.io/en/latest/installation_and_administration_guide/configuration

This snippet demonstrates how to configure the JSON Web Token (JWT) algorithm used for signing ID Tokens in OIDC. The selected algorithm ('RS256' in this example) determines the security method for token verification.

```javascript
config.oidc = {
    jwt_algorithm: 'RS256'
};
```

--------------------------------

### Generate OpenSSL Certificates for HTTPS

Source: https://fiware-idm.readthedocs.io/en/latest/installation_and_administration_guide/configuration

A shell script command to generate necessary SSL certificates for enabling HTTPS communication with Keyrock.

```bash
./generate_openssl_keys.sh
```

--------------------------------

### Provide Custom Translations in en.json

Source: https://fiware-idm.readthedocs.io/en/latest/installation_and_administration_guide/configuration

Defines custom translations for specific keys (e.g., 'auth.presentation.title') in a JSON file for a given language.

```json
{
  "auth": {
    "presentation": { "title": "My Identity Manager" }
  }
}

```

--------------------------------

### Configure Database Connection

Source: https://fiware-idm.readthedocs.io/en/latest/installation_and_administration_guide/configuration

This snippet details the database connection configuration, including host, port, username, password, database name, and dialect. This is essential for the Identity Management system to interact with its data store.

```javascript
config.database = {
    host: 'localhost',
    password: 'idm',
    username: 'root',
    database: 'idm',
    dialect: 'mysql',
    port: undefined
};
```

--------------------------------

### Run All Unit Tests - npm

Source: https://fiware-idm.readthedocs.io/en/latest/installation_and_administration_guide/sanity_check

This npm command executes all unit tests for the Keyrock installation. It assumes that the configuration files have been copied correctly. This is a quick way to ensure the core functionalities are working as expected.

```shell
npm run test
```

--------------------------------

### Validate Access Token and Get User Info (Bash)

Source: https://context7.com/context7/fiware-idm_readthedocs_io_en/llms.txt

This snippet shows how to validate an access token and retrieve associated user information. It involves making a GET request to the `/user` endpoint with the access token as a query parameter.

```bash
# Get user information with access token
curl "http://localhost:3000/user?access_token=cd8c8e41ab0db220315ed54f173087d281a4c686"

# Response with user details
# {
#     "organizations": [
#         {
#             "id": "13e88767-7473-472d-9c33-110c5bed2a57",
#             "name": "test_org",
#             "description": "my org",
#             "website": null,
#             "roles": [
#                 {

```

--------------------------------

### Authorization Decision Response Example

Source: https://fiware-idm.readthedocs.io/en/latest/oauth/oauth_documentation

An example JSON response when validating authorization, including the `authorization_decision` field indicating 'Permit' or 'Deny'. This response structure is similar to the user information response.

```JSON
{
  "organizations": [
    {
      "id": "13e88767-7473-472d-9c33-110c5bed2a57",
      "name": "test_org",
      "description": "my org",
      "website": null,
      "roles": [
        {
          "id": "9c4e8db4-a56b-4731-bfc6-7dd8fb2fbea3",
          "name": "test"
        }
      ]
    }
  ],
  "displayName": "My User",
  "roles": [
    {
      "id": "9c4e8db4-a56b-4731-bfc6-7dd8fb2fbea3",
      "name": "test"
    }
  ],
  "app_id": "ff03921a-a772-4220-9854-e2d499ae474a",
  "isGravatarEnabled": false,
  "email": "myuser@test.com",
  "id": "myuser",
  "authorization_decision": "Permit",
  "app_azf_domain": "",
  "username": "myuser"
}
```

--------------------------------

### Enable Headless Mode in Keyrock

Source: https://fiware-idm.readthedocs.io/en/latest/installation_and_administration_guide/configuration

Enables Keyrock to run without user sessions or a graphical user interface. In this mode, it only serves the PDP, IDM, and API endpoints.

```javascript
config.headless = true;
```

--------------------------------

### Enable HTTPS Configuration in Keyrock

Source: https://fiware-idm.readthedocs.io/en/latest/installation_and_administration_guide/configuration

Configures Keyrock to listen for HTTPS requests by enabling the feature and specifying the paths to the certificate and key files, along with the HTTPS port.

```javascript
config.https = {
    enabled: true,
    cert_file: 'certs/idm-2018-cert.pem',
    key_file: 'certs/idm-2018-key.pem',
    port: 443
};
```

--------------------------------

### Configure eIDAS Integration

Source: https://fiware-idm.readthedocs.io/en/latest/installation_and_administration_guide/configuration

This snippet shows the configuration for integrating with eIDAS, a European digital identity framework. It includes enabling the feature, specifying gateway and node hosts, and setting metadata expiration.

```javascript
config.eidas = {
    enabled: true,
    gateway_host: 'localhost',
    node_host: 'https://se-eidas.redsara.es/EidasNode/ServiceProvider',
    metadata_expiration: 60 * 60 * 24 * 365
};
```

--------------------------------

### Customize Logo in _styles.scss

Source: https://fiware-idm.readthedocs.io/en/latest/installation_and_administration_guide/configuration

Modifies the CSS to include a custom logo for the header, adjusting its background image, size, and positioning.

```scss
/****************************** Custom styles rewrite */

.logo-header .brand {
    background-image: url(../img/example.png);
    width: 150px;
    background-size: 150px 37px;
}

.logo-header {
    float: left;
}

.presentation {
    .media {
        height: auto;
        footer {
            margin-top: 15px;
        }
    }
}


```

--------------------------------

### Access Token Response

Source: https://fiware-idm.readthedocs.io/en/latest/oauth/oauth_documentation

Example of a successful access token response when JWT is enabled.

```APIDOC
## Access Token Response

### Description
This is an example of a successful response when requesting an access token with the `jwt` token type.

### Success Response (200)
- **access_token** (string) - The JWT access token.
- **token_type** (string) - The type of token, e.g., `jwt`.
- **refresh_token** (string) - The refresh token (omitted if `permanent` option was included in the request).

### Response Example
```json
{
    "access_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJvcmdhbml6YXRpb25zIjpbXSwiZGlzcGxheU5hbWUiOiIiLCJyb2xlcyI6W3siaWQiOiI1ZGNlMDVmMS1lMjg0LTQyMmEtYmViMS1mODhiZTMwYTg5MDAiLCJuYW1lIjoiYWFhYWEifV0sImFwcF9pZCI6IjFiNWJhY2U2LWIzZDUtNGE1ZC05MjU5LWY1MzI1OTg3NDk3ZSIsInRydXN0ZWRfYXBwcyI6W10sImlzR3JhdmF0YXJFbmFibGVkIjpmYWxzZSwiZW1haWwiOiJhZG1pbi50ZXN0LmNvbSIsImlkIjoiYWRtaW4iLCJhdXRob3JpemF0aW9uX2RlY2lzaW9uIjoiIiwiYXBwX2F6Zl9kb21haW4iOiIzclQ5d3NyOUVlaW9OZ0pDckJFQUFnIiwidXNlcm5hbWUiOiJhZG1pbiIsInR5cGUiOiJ1c2VyIiwiaWF0IjoxNTM5MDk1ODA2LCJleHAiOjE1MzkwOTk0MDZ9.-fYFHyPjPpA52gTEqMjppmERqiIZDgGKG5bJqVh0o68",
    "token_type":"jwt",
    "refresh_token":"a581cb04b116e26b175002bc2e05551042fafbda"
}
```
```

--------------------------------

### Configure Usage Control Settings

Source: https://fiware-idm.readthedocs.io/en/latest/installation_and_administration_guide/configuration

This snippet configures the Usage Control feature, which manages data usage. It includes enabling the feature and specifying the host and port for the Point-to-Point (PTP) communication.

```javascript
config.usage_control = {
    enabled: true,
    ptp: {
        host: 'localhost',
        port: 8090
    }
};
```

--------------------------------

### Enable Debug Mode in Keyrock

Source: https://fiware-idm.readthedocs.io/en/latest/installation_and_administration_guide/configuration

Activates debug mode, which displays detailed logs for resource requests and SQL statements executed against the database. This is useful for troubleshooting.

```javascript
config.debug = true;
```

--------------------------------

### Update Site Theme to Custom in config.js

Source: https://fiware-idm.readthedocs.io/en/latest/installation_and_administration_guide/configuration

Configures the Identity Manager to use a newly created custom theme by updating the 'theme' property in config.js.

```javascript
config.site = {
    title: 'Identity Manager',
    theme: 'example' // default/fiwarelab
};

```

--------------------------------

### Configure External Authorization Registry

Source: https://fiware-idm.readthedocs.io/en/latest/installation_and_administration_guide/configuration

Links Keyrock to an external authorization registry to store and provide authorization policies to external participants. Requires providing the URL of the external authorization registry.

```javascript
config.ar = {
    url: 'https://ar.example.com'
};

```

--------------------------------

### Validate Access Token and Get User Information

Source: https://context7.com/context7/fiware-idm_readthedocs_io_en/llms.txt

Retrieve user information and authorization details by providing a valid access token.

```APIDOC
## Validate Access Token and Get User Information

### Description
Retrieve user information and authorization decision using an access token.

### Method
GET

### Endpoint
`/user`

### Parameters
#### Query Parameters
- **access_token** (string) - Required - The access token to validate.

### Request Example
```bash
curl "http://localhost:3000/user?access_token=cd8c8e41ab0db220315ed54f173087d281a4c686"
```

### Response
#### Success Response (200)
- **organizations** (array) - List of organizations the user belongs to.
  - **id** (string) - Organization ID.
  - **name** (string) - Organization name.
  - **description** (string) - Organization description.
  - **website** (string) - Organization website (nullable).
  - **roles** (array) - List of roles within the organization.
    - **id** (string) - Role ID.
    - **name** (string) - Role name.
    - **description** (string) - Role description.

#### Response Example
```json
{
    "organizations": [
        {
            "id": "13e88767-7473-472d-9c33-110c5bed2a57",
            "name": "test_org",
            "description": "my org",
            "website": null,
            "roles": [
                {
                    "id": "role_id_1",
                    "name": "viewer",
                    "description": "Can view resources"
                }
            ]
        }
    ]
}
```
```

--------------------------------

### Configure Keyrock Host and Port

Source: https://fiware-idm.readthedocs.io/en/latest/installation_and_administration_guide/configuration

Sets the port Keyrock listens on when HTTPS is disabled and defines the domain name for Keyrock in production. For development, it should be set to 'http://localhost:' followed by the port.

```javascript
config.port = 80;
config.host = 'http://keyrock-domain-name.org:' + config.port;
```

--------------------------------

### Configure External Participant Registry

Source: https://fiware-idm.readthedocs.io/en/latest/installation_and_administration_guide/configuration

Enables Keyrock to use an external participant registry, allowing applications to use Keyrock as an identity provider without manual registration. Requires providing the registry URL and credentials (client ID, key, certificate).

```javascript
config.pr = {
    url: 'https://scheme.isharetest.net',
    client_id: 'EU.EORI.NLEXAMPLECOM',
    client_key: '...',
    client_crt: '...'
};

```

--------------------------------

### Configure IdM Mail Server Settings

Source: https://fiware-idm.readthedocs.io/en/latest/installation_and_administration_guide/configuration

Configures the IdM to send emails to users, specifying mail server host, port, sender address, and authentication details. Supports secure connections and authentication types. Requires configuration of a mail server like Postfix.

```javascript
config.mail = {
    host: 'idm_host',
    port: 25,
    from: 'noreply@host',
    secure: false,
    enable_authentication: false,
    auth: {
        type: 'type',
        user: 'username',
        pass: 'pass'
    }
};

```

--------------------------------

### Configure OAuth2.0 Settings

Source: https://fiware-idm.readthedocs.io/en/latest/installation_and_administration_guide/configuration

This snippet shows how to configure OAuth2.0 related settings for Keyrock, including token lifetimes, allow empty state, and ask authorization. These settings control various aspects of the OAuth2.0 flow and user consent management.

```javascript
config.oauth2 = {
    allowEmptyState: false,
    authorization_code_lifetime: 5 * 60,
    access_token_lifetime: 60 * 60,
    ask_authorization: true,
    refresh_token_lifetime: 60 * 60 * 24 * 14,
    unique_url: false
};
```

--------------------------------

### Create SQL View for External Authentication

Source: https://fiware-idm.readthedocs.io/en/latest/installation_and_administration_guide/configuration

This SQL statement creates a view named 'USER_VIEW' to expose user attributes from 'USERS' and 'ACTORS' tables in a format suitable for external authentication by Keyrock. It joins the tables on 'actor_id' and selects required fields like ID, password salt, encrypted password, email, and username.

```sql
CREATE VIEW USER_VIEW AS
    SELECT USERS.id, USERS.password_salt, USERS.encrypted_password as password, ACTORS.email, ACTORS.name as username
    FROM USERS,ACTORS
    WHERE USERS.actor_id = ACTORS.id;
```

--------------------------------

### Configure SQL External Authentication in config.js

Source: https://fiware-idm.readthedocs.io/en/latest/installation_and_administration_guide/configuration

This JavaScript configuration object enables and customizes SQL-based external authentication for FIWARE IDM. It specifies the connection details for the external database, the table or view containing user data, and encryption settings.

```javascript
config.external_auth = {
    enabled: true,
    id_prefix: 'external_',
    password_encryption_key: undefined,
    ecryption: 'bcyrpt',
    database: {
        host: 'localhost',
        port: undefined,
        database: 'idm',
        username: 'root',
        password: 'idm',
        user_table: 'user_view',
        dialect: 'mysql'
    }
};
```

--------------------------------

### Configure Keyrock Session Management

Source: https://fiware-idm.readthedocs.io/en/latest/installation_and_administration_guide/configuration

Sets up session management for Keyrock, defining a secret key for encrypting user sessions and the duration of the session. It is recommended to generate a new random secret key upon each server restart for security.

```javascript
config.session = {
    secret: require('crypto').randomBytes(20).toString('hex'),
    expires: 60 * 60 * 1000
};
```

--------------------------------

### Resource Owner Password Credentials Grant (Bash)

Source: https://context7.com/context7/fiware-idm_readthedocs_io_en/llms.txt

This snippet shows how to obtain access tokens directly using a user's username and password, suitable for trusted first-party applications. It also includes an example for requesting a permanent token.

```bash
# Request access token with user credentials
ID=a17bf9e3-628d-4000-8d25-37703975a528
SECRET=ac5df1fe-4caf-4ae6-9d21-60f3a9182887

curl -X POST \
     -H "Authorization: Basic $(echo -n $ID:$SECRET | base64 -w 0)" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=password&username=admin@test.com&password=1234" \
     http://localhost:3000/oauth2/token

# Response with access token
# {
#     "access_token": "cd8c8e41ab0db220315ed54f173087d281a4c686",
#     "token_type": "Bearer",
#     "expires_in": 3599,
#     "refresh_token": "8b96bc9dfbc8f1c0bd53e18720b6feb5b47de661",
#     "scope": ["bearer"]
# }

# Request permanent token (never expires)
curl -X POST \
     -H "Authorization: Basic $(echo -n $ID:$SECRET | base64 -w 0)" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=password&username=admin@test.com&password=1234&scope=permanent" \
     http://localhost:3000/oauth2/token
```

--------------------------------

### Default CORS Configuration in Keyrock

Source: https://fiware-idm.readthedocs.io/en/latest/installation_and_administration_guide/configuration

Defines the default Cross-Origin Resource Sharing (CORS) settings for Keyrock, enabling it to manage requests from different domains. This configuration specifies allowed HTTP methods and origins.

```javascript
config.cors = {
    enabled: true,
    options: {
        origin: '*',
        methods: ['GET', 'HEAD', 'PUT', 'PATCH', 'POST', 'DELETE'],
        allowedHeaders: undefined,
        exposedHeaders: undefined,
        credentials: undefined,
        maxAge: undefined,
        preflightContinue: false,
        optionsSuccessStatus: 204
    }
};
```

--------------------------------

### Configure Content Security Policy in Keyrock

Source: https://fiware-idm.readthedocs.io/en/latest/installation_and_administration_guide/configuration

Allows overriding the default Content Security Policy (CSP) directives in Keyrock, specifically for `form-action` and `script-src`. These values must be provided as arrays of allowed sources.

```javascript
config.csp = {
    form_action: undefined,
    script_src: undefined
};
```

--------------------------------

### Configure IdM Authorization Levels

Source: https://fiware-idm.readthedocs.io/en/latest/installation_and_administration_guide/configuration

Sets the authorization level for IdM, determining the complexity of policy checks. Supports basic (HTTP verb + path), payload (request body attributes), and advanced levels, with optional AuthZForce integration for advanced checks. Requires editing the configuration file.

```javascript
config.authorization = {
    level: 'basic', // basic|payload|advanced
    authzforce: {
        enabled: false,
        host: 'localhost',
        port: 8080
    }
};

```

--------------------------------

### Configure IdM Email Domain Filtering

Source: https://fiware-idm.readthedocs.io/en/latest/installation_and_administration_guide/configuration

Enables email domain filtering for user sign-ups in Keyrock. Supports 'whitelist' for allowed domains or 'blacklist' for blocked domains. Email domains are listed one per line in '/etc/email_list'. If set to null or undefined, no filtering is performed.

```javascript
config.email_list_type = 'whitelist';

```

--------------------------------

### Configure LDAP External Authentication in config.js

Source: https://fiware-idm.readthedocs.io/en/latest/installation_and_administration_guide/configuration

This JavaScript configuration object enables and customizes LDAP-based external authentication for FIWARE IDM. It specifies connection details for the LDAP server, including host, port, reader credentials, domain suffix, and attribute mappings for user ID, username, and email.

```javascript
// External user authentication with LDAP
// Testing credentials from https://www.forumsys.com/tutorials/integration-how-to/ldap/online-ldap-test-server/
config.external_auth_ldap = {
    enabled: true,
    id_prefix: 'external_ldap_',
    database: {
        host: 'ldap.forumsys.com',
        port: 389,
        reader_dn: 'cn=read-only-admin,dc=example,dc=com',
        reader_password: 'password',
        suffix: 'dc=example,dc=com',
        idAttribute: 'uid',
        usernameAttribute: 'uid',
        emailAttribute: 'mail'
    }
};
```

--------------------------------

### GET /user - Get User Information

Source: https://fiware-idm.readthedocs.io/en/latest/oauth/oauth_documentation

Retrieves detailed information about a user, including their organizations, roles, and application-specific data. Requires an access token.

```APIDOC
## GET /user - Get User Information

### Description
Retrieves detailed information about a user, including their organizations, roles, and application-specific data. Requires an access token.

### Method
GET

### Endpoint
/user

### Parameters
#### Query Parameters
- **access_token** (string) - Required - The access token for authentication.

### Request Example
```
GET /user?access_token=2YotnFZFEjr1zCsicMWpAA
```

### Response
#### Success Response (200)
- **organizations** (array) - List of organizations the user belongs to, each with id, name, description, website, and roles.
- **displayName** (string) - The user's display name.
- **roles** (array) - List of roles assigned to the user at the global level.
- **app_id** (string) - The application ID associated with the user's context.
- **isGravatarEnabled** (boolean) - Indicates if Gravatar is enabled for the user.
- **email** (string) - The user's email address.
- **id** (string) - The unique identifier for the user.
- **authorization_decision** (string) - The authorization decision for the user (if applicable).
- **app_azf_domain** (string) - The authorization domain within the application.
- **username** (string) - The user's username.

#### Response Example
```json
{
  "organizations": [
    {
      "id": "13e88767-7473-472d-9c33-110c5bed2a57",
      "name": "test_org",
      "description": "my org",
      "website": null,
      "roles": [
        {
          "id": "9c4e8db4-a56b-4731-bfc6-7dd8fb2fbea3",
          "name": "test"
        }
      ]
    }
  ],
  "displayName": "My User",
  "roles": [
    {
      "id": "9c4e8db4-a56b-4731-bfc6-7dd8fb2fbea3",
      "name": "test"
    }
  ],
  "app_id": "ff03921a-a772-4220-9854-e2d499ae474a",
  "isGravatarEnabled": false,
  "email": "myuser@test.com",
  "id": "myuser",
  "authorization_decision": "",
  "app_azf_domain": "",
  "username": "myuser"
}
```
```

--------------------------------

### Get User Information

Source: https://fiware-idm.readthedocs.io/en/latest/oauth/oauth_documentation

Retrieves information and roles associated with a user based on their access token. The access token is provided as a query parameter in the GET request.

```HTTP
GET /user?access_token=2YotnFZFEjr1zCsicMWpAA
```

--------------------------------

### Customize Theme Colors in _colors.scss

Source: https://fiware-idm.readthedocs.io/en/latest/installation_and_administration_guide/configuration

Overrides default color variables (e.g., brand-primary, brand-secondary) for a custom theme.

```scss
/****************************** Custom colors rewrite */

$brand-primary: purple;
$brand-secundary: orange;


```

--------------------------------

### Configure Default Language in config.js

Source: https://fiware-idm.readthedocs.io/en/latest/installation_and_administration_guide/configuration

Sets the default language for the Keyrock system. The 'defaultLang' property specifies the language code.

```javascript
config.lang = {
    defaultLang: 'en'
};

```

--------------------------------

### Create Application via API

Source: https://context7.com/context7/fiware-idm_readthedocs_io_en/llms.txt

Shows how to register a new OAuth2 application with Keyrock using the API. This `curl` command requires an existing `X-Auth-token` obtained previously. It sends application details such as name, description, redirect URI, and supported grant types.

```bash
# Create application using API token
curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "X-Auth-token: 04c5b070-4292-4b3f-911b-36a103f3ac3f" \
     --data-binary '{ \
  "application": { \
    "name": "Test_application 1", \
    "description": "My test application", \
    "redirect_uri": "http://localhost/login", \
    "url": "http://localhost", \
    "grant_type": [ \
      "authorization_code", \
      "implicit", \
      "password" \
    ],
    "token_types": [
        "jwt",
        "permanent"
    ]
  }
}' \
'http://localhost:3000/v1/applications'

# Response with application credentials
# { 
#     "application": { 
#         "id": "a17bf9e3-628d-4000-8d25-37703975a528", 
#         "secret": "ac5df1fe-4caf-4ae6-9d21-60f3a9182887", 
#         "image": "default",

```

--------------------------------

### IdM GE API Overview

Source: https://fiware-idm.readthedocs.io/en/latest/api/introduction

This section provides an overview of the Identity Manager (IdM) GE API, its purpose, and the expected knowledge of the user.

```APIDOC
## IdM GE API

### Description
Identity Manager (IdM) GE API specifications comply with existing standards for authentication and user and provide access information. This specification is intended for Service Consumers (with development skills) and Cloud Providers.

The API user should be familiar with:
  * RESTful web services.
  * HTTP/1.1.
  * JSON and/or XML data serialization formats.

Users can perform these actions through the API:
  * Authentication.
  * Manage Applications.
  * Manage Users.
  * Manage Organizations.
  * Manage Roles.
  * Manage Permissions.
  * Manage IoT Agents.
  * Manage Pep Proxies.

For a full description of how to make API requests and obtain an authentication token, refer to the Keyrock Apiary.
```

--------------------------------

### Access MySQL Database Console

Source: https://fiware-idm.readthedocs.io/en/latest/installation_and_administration_guide/system_administration

Command to access the MySQL database console. Requires the MySQL host and username, and will prompt for the password. This is a standard way to interact with MySQL databases.

```bash
mysql -u [mysql_host] -u [username] -p
```

--------------------------------

### POST /v1/applications

Source: https://context7.com/context7/fiware-idm_readthedocs_io_en/llms.txt

Register a new OAuth2 application with Keyrock programmatically.

```APIDOC
## POST /v1/applications

### Description
Register a new OAuth2 application with Keyrock programmatically.

### Method
POST

### Endpoint
`/v1/applications`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **application** (object) - Required - Details of the application to create.
  - **name** (string) - Required - The name of the application.
  - **description** (string) - Optional - A description for the application.
  - **redirect_uri** (string) - Required - The redirect URI for OAuth2.
  - **url** (string) - Optional - The URL of the application.
  - **grant_type** (array of strings) - Required - The allowed OAuth2 grant types.
  - **token_types** (array of strings) - Required - The types of tokens to be generated.

### Request Example
```json
{
  "application": {
    "name": "Test_application 1",
    "description": "My test application",
    "redirect_uri": "http://localhost/login",
    "url": "http://localhost",
    "grant_type": [
      "authorization_code",
      "implicit",
      "password"
    ],
    "token_types": [
        "jwt",
        "permanent"
    ]
  }
}
```

### Response
#### Success Response (200 or 201)
- **application** (object) - Details of the created application.
  - **id** (string) - The unique identifier for the application.
  - **secret** (string) - The client secret for the application.
  - **image** (string) - The application's image identifier.

#### Response Example
```json
{
    "application": {
        "id": "a17bf9e3-628d-4000-8d25-37703975a528",
        "secret": "ac5df1fe-4caf-4ae6-9d21-60f3a9182887",
        "image": "default"
    }
}
```

**Note:** This endpoint requires an `X-Auth-token` header with a valid API token.
```

--------------------------------

### Client Credentials Grant

Source: https://context7.com/context7/fiware-idm_readthedocs_io_en/llms.txt

Obtain access tokens for machine-to-machine authentication. This flow uses only the client's credentials to get an access token.

```APIDOC
## Client Credentials Grant

### Description
Obtain access tokens for machine-to-machine authentication.

### Method
POST

### Endpoint
`/oauth2/token`

### Parameters
#### Request Body
- **grant_type** (string) - Required - Must be `client_credentials`.

### Request Example
```bash
ID=a17bf9e3-628d-4000-8d25-37703975a528
SECRET=ac5df1fe-4caf-4ae6-9d21-60f3a9182887

curl -X POST \
     -H "Authorization: Basic $(echo -n $ID:$SECRET | base64 -w 0)" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=client_credentials" \
     http://localhost:3000/oauth2/token
```

### Response
#### Success Response (200)
- **access_token** (string) - The access token.
- **token_type** (string) - The type of token (e.g., `bearer`).
- **expires_in** (integer) - The time in seconds until the token expires.

#### Response Example
```json
{
    "access_token": "2YotnFZFEjr1zCsicMWpAA",
    "token_type": "bearer",
    "expires_in": 3600
}
```
```

--------------------------------

### Configure Keyrock Password Encryption

Source: https://fiware-idm.readthedocs.io/en/latest/installation_and_administration_guide/configuration

Configures password encryption settings for Keyrock. While salt password is the current standard, this allows for traditional encryption if salt passwords are not used.

```javascript
config.password_encryption = {
    key: 'idm_encryption'
};
```

--------------------------------

### GET /user - Validate Authorization

Source: https://fiware-idm.readthedocs.io/en/latest/oauth/oauth_documentation

Retrieves user information and checks authorization for a specific action on a resource within an application. Requires an access token and action/resource details.

```APIDOC
## GET /user - Validate Authorization

### Description
Retrieves user information and checks authorization for a specific action on a resource within an application. Requires an access token and action/resource details. This endpoint is useful when Keyrock is configured as a Policy Decision Point (PDP).

### Method
GET

### Endpoint
/user

### Parameters
#### Query Parameters
- **access_token** (string) - Required - The access token for authentication.
- **action** (string) - Required - The action to authorize (e.g., `GET`).
- **resource** (string) - Required - The resource to check authorization against (e.g., `myResource`).
- **app_id** (string) - Required - The ID of the application for which authorization is being checked.

### Request Example
```
GET /user?access_token=2YotnFZFEjr1zCsicMWpAA&action=GET&resource=myResource&app_id=ea3edd2e-2220-4489-af7d-6d60fffb7d1a
```

### Response
#### Success Response (200)
- **organizations** (array) - List of organizations the user belongs to.
- **displayName** (string) - The user's display name.
- **roles** (array) - List of roles assigned to the user.
- **app_id** (string) - The application ID.
- **isGravatarEnabled** (boolean) - Indicates if Gravatar is enabled.
- **email** (string) - The user's email address.
- **id** (string) - The user's unique identifier.
- **authorization_decision** (string) - The authorization decision (e.g., `Permit` or `Deny`).
- **app_azf_domain** (string) - The authorization domain within the application.
- **username** (string) - The user's username.

#### Response Example
```json
{
  "organizations": [
    {
      "id": "13e88767-7473-472d-9c33-110c5bed2a57",
      "name": "test_org",
      "description": "my org",
      "website": null,
      "roles": [
        {
          "id": "9c4e8db4-a56b-4731-bfc6-7dd8fb2fbea3",
          "name": "test"
        }
      ]
    }
  ],
  "displayName": "My User",
  "roles": [
    {
      "id": "9c4e8db4-a56b-4731-bfc6-7dd8fb2fbea3",
      "name": "test"
    }
  ],
  "app_id": "ff03921a-a772-4220-9854-e2d499ae474a",
  "isGravatarEnabled": false,
  "email": "myuser@test.com",
  "id": "myuser",
  "authorization_decision": "Permit",
  "app_azf_domain": "",
  "username": "myuser"
}
```
```
Tokens:
Raw