diff --git a/404.html b/404.html index eddea9db0..c18e6091a 100644 --- a/404.html +++ b/404.html @@ -7,13 +7,13 @@ - +
Skip to main content

Page Not Found

We could not find what you were looking for.

Please contact the owner of the site that linked you to the original URL and let them know their link is broken.

- + \ No newline at end of file diff --git a/admin-portal/index.html b/admin-portal/index.html index 8b1d54b0d..27afb0f61 100644 --- a/admin-portal/index.html +++ b/admin-portal/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Admin Portal

The Admin Portal provides the Shield administrators with a centralized interface for managing the Raystack/Shield platform. This README will guide you through the installation, setup, and usage of the Admin Portal.

Features​

Many of these features are still in development and represents an exhautive list of all the details in our Roadmap for the Admin Portal

  • Dashboard for an overview of system health and key metrics
  • Tenant (organization) management for multi-tenancy support
  • User authentication and access control
  • User management with role-based access control
  • Roles and permission management for fine-tuning Shield's behavior
  • Integration with external authentication identity providers/ configure Magic Links/ OTP based sign-ups
  • Domain Verification for Organizations
  • Audit Logs for monitoring and much more...

Starting the Admin Portal​

Make sure you have the Shield server up and running. For details refer installations and configurations

Change the current working directory to ui in Shield

$ cd ui

Create a .env file or export SHILD_API_URL environment variable for communication with the Shield server.

.env
# provide the shield server url
SHILD_API_URL=http://localhost:8000

Finally, to start the Admin portal, run the following commands:

# install all dependencies
$ npm install
# start the Admin Portal UI
$ npm run dev

Open http://localhost:5173/console with your browser to see the result.

- + \ No newline at end of file diff --git a/apis/admin-service-create-permission/index.html b/apis/admin-service-create-permission/index.html index c83c5c543..3d41bd394 100644 --- a/apis/admin-service-create-permission/index.html +++ b/apis/admin-service-create-permission/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Create platform permission​

Creates a permission. It can be used to grant permissions to all the resources in a Shield instance.

Request Body required
    bodies object[]
  • Array [
    • name string

    The name of the permission. It should be unique across a Shield instance and can contain only alphanumeric characters.

    namespace namespace should be in service/resource format

    The namespace of the permission.The namespace should be in service/resource format.
    Example:app/guardian

    metadata object

    The metadata object for permissions that can hold key value pairs.

    title string

    The title can contain any UTF-8 character, used to provide a human-readable name for the permissions. Can also be left empty.

    key string

    Permission path key is composed of three parts, 'service.resource.verb'. Where 'service.resource' works as a namespace for the 'verb'.

  • ]
Responses

A successful response.

Schema
    permissions object[]
  • Array [
    • id string
    name string
    title string
    createdAt date-time

    The time the permission was created.

    updatedAt date-time

    The time the permission was last updated.

    namespace string
    metadata object
    key string

    Permission path key is composed of three parts, 'service.resource.verb'. Where 'service.resource' works as a namespace for the 'verb'.

  • ]
Loading...
- + \ No newline at end of file diff --git a/apis/admin-service-create-role/index.html b/apis/admin-service-create-role/index.html index 06b1aac14..eefec591c 100644 --- a/apis/admin-service-create-role/index.html +++ b/apis/admin-service-create-role/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Create platform role​

Creates a platform wide role. It can be used to grant permissions to all the resources in a Shield instance.

Request Body required
    name string
    permissions string[]
    metadata object
    title string
Responses

A successful response.

Schema
    role object
    id string
    name string
    permissions string[]
    title string
    metadata object
    createdAt date-time

    The time the role was created.

    updatedAt date-time

    The time the role was last updated.

    orgId string
    state string
Loading...
- + \ No newline at end of file diff --git a/apis/admin-service-delete-permission/index.html b/apis/admin-service-delete-permission/index.html index c83dd0852..1ff0b1cf6 100644 --- a/apis/admin-service-delete-permission/index.html +++ b/apis/admin-service-delete-permission/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Delete platform permission​

Delete platform permission

Path Parameters
    id string required
Responses

A successful response.

Schema

    object

Loading...
- + \ No newline at end of file diff --git a/apis/admin-service-delete-role/index.html b/apis/admin-service-delete-role/index.html index 9fade8144..d6b4ce6b2 100644 --- a/apis/admin-service-delete-role/index.html +++ b/apis/admin-service-delete-role/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Delete platform role​

Delete a platform wide role and all of its relations.

Path Parameters
    id string required

    The role id to delete.

Responses

A successful response.

Schema

    object

Loading...
- + \ No newline at end of file diff --git a/apis/admin-service-list-all-organizations/index.html b/apis/admin-service-list-all-organizations/index.html index 61058c877..bbe015cc6 100644 --- a/apis/admin-service-list-all-organizations/index.html +++ b/apis/admin-service-list-all-organizations/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

List all organizations​

Lists all the organizations in a Shield instance. It can be filtered by user and state.

Query Parameters
    userId string

    The user id to filter by.

    state string

    The state to filter by. It can be enabled or disabled.

Responses

A successful response.

Schema
    organizations object[]
  • Array [
    • id string
    name string
    title string
    metadata object
    createdAt date-time

    The time the organization was created.

    updatedAt date-time

    The time the organization was last updated.

  • ]
Loading...
- + \ No newline at end of file diff --git a/apis/admin-service-list-all-users/index.html b/apis/admin-service-list-all-users/index.html index 2558972e9..523793b81 100644 --- a/apis/admin-service-list-all-users/index.html +++ b/apis/admin-service-list-all-users/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

List all users​

Lists all the users from all the organizations in a Shield instance. It can be filtered by keyword, organization, group and state.

Query Parameters
    pageSize int32

    The maximum number of users to return per page. The default is 50.

    pageNum int32

    The page number to return. The default is 1.

    keyword string

    The keyword to search for. It can be a user's name, email,metadata or id.

    orgId string

    The organization id to filter by.

    groupId string

    The group id to filter by.

    state string

    The state to filter by. It can be enabled or disabled.

Responses

A successful response.

Schema
    count int32
    users object[]
  • Array [
    • id string
    name can either be empty or must start with a character

    Unique name of the user.

    title string

    Name of the user.

    email string
    metadata object
    createdAt date-time

    The time the user was created.

    updatedAt date-time

    The time the user was last updated.

    state string
  • ]
Loading...
- + \ No newline at end of file diff --git a/apis/admin-service-list-groups/index.html b/apis/admin-service-list-groups/index.html index 12e74c143..710146237 100644 --- a/apis/admin-service-list-groups/index.html +++ b/apis/admin-service-list-groups/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

List all groups​

Lists all the groups from all the organizations in a Shield instance. It can be filtered by organization and state.

Query Parameters
    orgId string

    The organization id to filter by.

    state string

    The state to filter by. It can be enabled or disabled.

Responses

A successful response.

Schema
    groups object[]
  • Array [
    • id string
    name string
    title string
    orgId string
    metadata object
    createdAt date-time

    The time the group was created.

    updatedAt date-time

    The time the group was last updated.

  • ]
Loading...
- + \ No newline at end of file diff --git a/apis/admin-service-list-policies/index.html b/apis/admin-service-list-policies/index.html index 035effe38..b9d94f78c 100644 --- a/apis/admin-service-list-policies/index.html +++ b/apis/admin-service-list-policies/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

List all policies​

Lists all the policies from all the organizations in a Shield instance. It can be filtered by organization, project, user, role and group.

Query Parameters
    orgId string

    The organization id to filter by.

    projectId string

    The project id to filter by.

    userId string

    The user id to filter by.

    roleId string

    The role id to filter by.

    groupId string

    The group id to filter by.

Responses

A successful response.

Schema
    policies object[]
  • Array [
    • id string
    title string
    createdAt date-time

    The time the policy was created.

    updatedAt date-time

    The time the policy was last updated.

    roleId string
    resource namespace:uuid
    principal namespace:uuid
    metadata object
  • ]
Loading...
- + \ No newline at end of file diff --git a/apis/admin-service-list-projects/index.html b/apis/admin-service-list-projects/index.html index 07766488a..08fea42e0 100644 --- a/apis/admin-service-list-projects/index.html +++ b/apis/admin-service-list-projects/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

List all projects​

Lists all the projects from all the organizations in a Shield instance. It can be filtered by organization and state.

Query Parameters
    orgId string

    The organization id to filter by.

    state string

    The state to filter by. It can be enabled or disabled.

Responses

A successful response.

Schema
    projects object[]
  • Array [
    • id string
    name string
    title string
    orgId string
    metadata object
    createdAt date-time

    The time the project was created.

    updatedAt date-time

    The time the project was last updated.

  • ]
Loading...
- + \ No newline at end of file diff --git a/apis/admin-service-list-relations/index.html b/apis/admin-service-list-relations/index.html index 5c22e6f19..403354ceb 100644 --- a/apis/admin-service-list-relations/index.html +++ b/apis/admin-service-list-relations/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

List all relations​

List all relations

Responses

A successful response.

Schema
    relations object[]
  • Array [
    • id string
    createdAt date-time

    The time the relation was created.

    updatedAt date-time

    The time the relation was last updated.

    subjectSubRelation string
    relation string
    object objectnamespace:id
    subject subjectnamespace:id
  • ]
Loading...
- + \ No newline at end of file diff --git a/apis/admin-service-list-resources/index.html b/apis/admin-service-list-resources/index.html index 6c6d41bb7..a75e57457 100644 --- a/apis/admin-service-list-resources/index.html +++ b/apis/admin-service-list-resources/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

List all resources​

Lists all the resources from all the organizations in a Shield instance. It can be filtered by user, project, organization and namespace.

Query Parameters
    userId string

    The user id to filter by.

    projectId string

    The project id to filter by.

    organizationId string

    The organization id to filter by.

    namespace string

    The namespace to filter by.

Responses

A successful response.

Schema
    resources object[]
  • Array [
    • id string
    name string

    Name of the resource. Must be unique within the project.

    createdAt date-time

    The time the resource was created.

    updatedAt date-time

    The time the resource was last updated.

    urn string
    projectId string
    namespace string
    principal string
    metadata object
  • ]
Loading...
- + \ No newline at end of file diff --git a/apis/admin-service-update-permission/index.html b/apis/admin-service-update-permission/index.html index 6940bd00d..e7c1d297a 100644 --- a/apis/admin-service-update-permission/index.html +++ b/apis/admin-service-update-permission/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Update platform permission​

Updates a permission by ID. It can be used to grant permissions to all the resources in a Shield instance.

Path Parameters
    id string required
Request Body required
    name string

    The name of the permission. It should be unique across a Shield instance and can contain only alphanumeric characters.

    namespace namespace should be in service/resource format

    The namespace of the permission.The namespace should be in service/resource format.
    Example:app/guardian

    metadata object

    The metadata object for permissions that can hold key value pairs.

    title string

    The title can contain any UTF-8 character, used to provide a human-readable name for the permissions. Can also be left empty.

    key string

    Permission path key is composed of three parts, 'service.resource.verb'. Where 'service.resource' works as a namespace for the 'verb'.

Responses

A successful response.

Schema
    permission object
    id string
    name string
    title string
    createdAt date-time

    The time the permission was created.

    updatedAt date-time

    The time the permission was last updated.

    namespace string
    metadata object
    key string

    Permission path key is composed of three parts, 'service.resource.verb'. Where 'service.resource' works as a namespace for the 'verb'.

Loading...
- + \ No newline at end of file diff --git a/apis/shield-administration-api/index.html b/apis/shield-administration-api/index.html index 311a3bddf..ccfb3baed 100644 --- a/apis/shield-administration-api/index.html +++ b/apis/shield-administration-api/index.html @@ -7,13 +7,13 @@ - +
Skip to main content
Version: 0.2.0

Shield Administration API

The Shield APIs adhere to the OpenAPI specification, also known as Swagger, which provides a standardized approach for designing, documenting, and consuming RESTful APIs. With OpenAPI, you gain a clear understanding of the API endpoints, request/response structures, and authentication mechanisms supported by the Shield APIs. By leveraging the OpenAPI specification, developers can easily explore and interact with the Shield APIs using a variety of tools and libraries. The OpenAPI specification enables automatic code generation, interactive API documentation, and seamless integration with API testing frameworks, making it easier than ever to integrate Shield into your existing applications and workflows.

Authentication​

use Client ID as username and Client Secret as password

Security Scheme Type:http
HTTP Authorization Scheme:basic

Contact

Raystack Foundation: hello@raystack.orgURL: https://raystack.org/

License

Apache 2.0
- + \ No newline at end of file diff --git a/apis/shield-service-accept-organization-invitation/index.html b/apis/shield-service-accept-organization-invitation/index.html index 7250c2de1..19d83e7ff 100644 --- a/apis/shield-service-accept-organization-invitation/index.html +++ b/apis/shield-service-accept-organization-invitation/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Accept pending invitation​

Accept pending invitation queued for an organization. The user will be added to the organization and groups defined in the invitation

Path Parameters
    orgId string required
    id string required
Responses

A successful response.

Schema

    object

Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-add-group-users/index.html b/apis/shield-service-add-group-users/index.html index ad13e3157..d694b035a 100644 --- a/apis/shield-service-add-group-users/index.html +++ b/apis/shield-service-add-group-users/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Add group user​

Adds a principle(user and service-users) to a group, existing users in the group will be ignored. A group can't have nested groups as members.

Path Parameters
    orgId string required
    id string required
Request Body required
    userIds string[]
Responses

A successful response.

Schema

    object

Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-add-organization-users/index.html b/apis/shield-service-add-organization-users/index.html index 5d70d6f83..ba23e33ab 100644 --- a/apis/shield-service-add-organization-users/index.html +++ b/apis/shield-service-add-organization-users/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Add organization user​

Add a user to an organization. A user must exists in Shield before adding it to an org. This request will fail if the user doesn't exists

Path Parameters
    id string required
Request Body required
    userIds string[]

    List of user IDs to be added to the organization.

Responses

A successful response.

Schema

    object

Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-auth-callback-2/index.html b/apis/shield-service-auth-callback-2/index.html index 23a433a68..9eab1e43c 100644 --- a/apis/shield-service-auth-callback-2/index.html +++ b/apis/shield-service-auth-callback-2/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Callback from a strategy​

Callback from a strategy. This is the endpoint where the strategy will redirect the user after successful authentication. This endpoint will be called with the code and state query parameters. The code will be used to get the access token from the strategy and the state will be used to get the return_to url from the session and redirect the user to that url.

Request Body required
    strategyName strategy_name will not be set for oidc but can be utilized for methods like email magic links
    state for oidc & magic links
    code string
Responses

A successful response.

Schema

    object

Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-auth-callback/index.html b/apis/shield-service-auth-callback/index.html index 3351819d5..d3a970c92 100644 --- a/apis/shield-service-auth-callback/index.html +++ b/apis/shield-service-auth-callback/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Callback from a strategy​

Callback from a strategy. This is the endpoint where the strategy will redirect the user after successful authentication. This endpoint will be called with the code and state query parameters. The code will be used to get the access token from the strategy and the state will be used to get the return_to url from the session and redirect the user to that url.

Query Parameters
    strategyName string

    strategy_name will not be set for oidc but can be utilized for methods like email magic links

    state string

    for oidc & magic links

    code string
Responses

A successful response.

Schema

    object

Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-auth-logout-2/index.html b/apis/shield-service-auth-logout-2/index.html index 8637020b6..d153b3435 100644 --- a/apis/shield-service-auth-logout-2/index.html +++ b/apis/shield-service-auth-logout-2/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Logout from a strategy​

Logout from a strategy

Responses

A successful response.

Schema

    object

Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-auth-logout/index.html b/apis/shield-service-auth-logout/index.html index b7398cec6..d2d638f98 100644 --- a/apis/shield-service-auth-logout/index.html +++ b/apis/shield-service-auth-logout/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Logout from a strategy​

Logout from a strategy

Responses

A successful response.

Schema

    object

Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-auth-token/index.html b/apis/shield-service-auth-token/index.html index 669bd0ddb..6e204d6dc 100644 --- a/apis/shield-service-auth-token/index.html +++ b/apis/shield-service-auth-token/index.html @@ -7,7 +7,7 @@ - + @@ -15,7 +15,7 @@
Skip to main content

Generate access token by given credentials​

Access token can be generated by providing the credentials in the request body/header. The credentials can be client id and secret or service account generated key jwt. Use the generated access token in Authorization header to access the shield resources.

Request Body required
    grantType grant_type can be one of the following: - client_credentials - urn:ietf:params:oauth:grant-type:jwt-bearer
    clientId client_id and client_secret are required for grant_type client_credentials
    clientSecret string
    assertion assertion is required for grant_type urn:ietf:params:oauth:grant-type:jwt-bearer
Responses

A successful response.

Schema
    accessToken string
    tokenType string
Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-authenticate-2/index.html b/apis/shield-service-authenticate-2/index.html index deb329879..036646f56 100644 --- a/apis/shield-service-authenticate-2/index.html +++ b/apis/shield-service-authenticate-2/index.html @@ -7,7 +7,7 @@ - + @@ -16,7 +16,7 @@ will be skipped unless this is set to true, useful in browser

If set to true, location header will be set for redirect

returnTo by default, after successful authentication no operation will be performed to apply redirection in case of browsers, provide a url that will be used for redirection after authentication

URL to redirect after successful authentication.
Example:"https://shield.example.com"

email email of the user for magic links

Email of the user to authenticate. Used for magic links.
Example:example@acme.org

Responses

A successful response.

Schema
    endpoint string
    state string
Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-authenticate/index.html b/apis/shield-service-authenticate/index.html index 20bec031e..2108075ce 100644 --- a/apis/shield-service-authenticate/index.html +++ b/apis/shield-service-authenticate/index.html @@ -7,7 +7,7 @@ - + @@ -19,7 +19,7 @@ for redirection after authentication

URL to redirect after successful authentication.
Example:"https://shield.example.com"

email string

email of the user for magic links

Email of the user to authenticate. Used for magic links.
Example:example@acme.org

Responses

A successful response.

Schema
    endpoint string
    state string
Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-check-resource-permission/index.html b/apis/shield-service-check-resource-permission/index.html index dfb955513..8e47ab35e 100644 --- a/apis/shield-service-check-resource-permission/index.html +++ b/apis/shield-service-check-resource-permission/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Check​

Returns true if a principal has required permissions to access a resource and false otherwise.
Note the principal can be a user or a service account, and Shield will the credentials from the current logged in principal from the session cookie (if any), or the client id and secret (in case of service users) or the access token (in case of human user accounts).

Request Body required
    objectId string

    Deprecated. Use resource field instead.

    objectNamespace string

    Deprecated. Use resource field instead.

    permission string required

    the permission name to check.
    Example: get or list

    resource string

    namespace:uuid or namespace:name of the org or project, and namespace:urn of a resource under a project. In case of an org/project either provide the complete namespace (app/organization) or Shield can also parse aliases for the same as org or project.
    Example: organization:92f69c3a-334b-4f25-90b8-4d4f3be6b825 or app/project:project-name or compute/instance:92f69c3a-334b-4f25-90b8-4d4f3be6b825

Responses

A successful response.

Schema
    status boolean
Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-create-group/index.html b/apis/shield-service-create-group/index.html index 1bef0f324..7a6457d05 100644 --- a/apis/shield-service-create-group/index.html +++ b/apis/shield-service-create-group/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Create group​

Create a new group in an organization which serves as a container for users. The group can be assigned roles and permissions and can be used to manage access to resources. Also a group can also be assigned to other groups.

Path Parameters
    orgId string required

    The organization ID to which the group belongs to.

Request Body required
    name string required

    The name of the group. The name must be unique within the entire Shield instance. The name can contain only alphanumeric characters, dashes and underscores.

    title string

    The title can contain any UTF-8 character, used to provide a human-readable name for the group. Can also be left empty.

    metadata object

    Metadata object for groups that can hold key value pairs defined in Group Metaschema. The metadata object can be used to store arbitrary information about the group such as labels, descriptions etc. The default Group Metaschema contains labels and descripton fields. Update the Group Metaschema to add more fields.
    Example:{"labels": {"key": "value"}, "description": "Group description"}

Responses

A successful response.

Schema
    group object
    id string
    name string
    title string
    orgId string
    metadata object
    createdAt date-time

    The time the group was created.

    updatedAt date-time

    The time the group was last updated.

Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-create-meta-schema/index.html b/apis/shield-service-create-meta-schema/index.html index 8abf8b537..dd6ad159b 100644 --- a/apis/shield-service-create-meta-schema/index.html +++ b/apis/shield-service-create-meta-schema/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Create metaschema​

Create a new metadata schema. The metaschema name must be unique within the entire Shield instance and can contain only alphanumeric characters, dashes and underscores. The metaschema schema must be a valid JSON schema.Please refer to https://json-schema.org/ to know more about json schema.
Example: {name:"user",schema:{"type":"object","properties":{"label":{"type":"object","additionalProperties":{"type":"string"}},"description":{"type":"string"}}}}

Request Body required
    name string required

    The name of the metaschema. The name must be unique within the entire Shield instance. The name can contain only alphanumeric characters, dashes and underscores.

    schema string required

    The schema of the metaschema. The schema must be a valid JSON schema.Please refer to https://json-schema.org/ to know more about json schema.

Responses

A successful response.

Schema
    metaschema object
    id string

    The unique metaschema uuid.

    name string
    schema string

    The metaschema json schema.

    createdAt date-time

    The time when the metaschema was created.

    updatedAt date-time

    The time when the metaschema was updated.

Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-create-organization-invitation/index.html b/apis/shield-service-create-organization-invitation/index.html index ab8214f69..a123ea46a 100644 --- a/apis/shield-service-create-organization-invitation/index.html +++ b/apis/shield-service-create-organization-invitation/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Invite user​

Invite users to an organization, if the user doesn't exists, it will be created and notified. Invitations expire in 7 days

Path Parameters
    orgId string required

    unique id of the organization to which user is invited

Request Body required
    userId string required

    user_id is email id of user who are invited inside the organization. If user is not registered on the platform, it will be notified

    groupIds string[]

    list of group ids to which user needs to be added as a member.

Responses

A successful response.

Schema
    invitation object
    id string

    The unique invitation identifier.

    userId string

    The user email of the invited user.

    orgId string

    The organization id to which the user is invited.

    groupIds string[]

    The list of group ids to which the user is invited.

    metadata object

    The metadata of the invitation.

    createdAt date-time

    The time when the invitation was created.

    expiresAt date-time

    The time when the invitation expires.

Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-create-organization-role/index.html b/apis/shield-service-create-organization-role/index.html index 8458b9579..305c82fd8 100644 --- a/apis/shield-service-create-organization-role/index.html +++ b/apis/shield-service-create-organization-role/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Create organization role​

Create a custom role under an organization. This custom role will only be available for assignment to the principles within the organization.

Path Parameters
    orgId string required

    The organization ID to which the role belongs to.

Request Body required
    name string
    permissions string[]
    metadata object
    title string
Responses

A successful response.

Schema
    role object
    id string
    name string
    permissions string[]
    title string
    metadata object
    createdAt date-time

    The time the role was created.

    updatedAt date-time

    The time the role was last updated.

    orgId string
    state string
Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-create-organization/index.html b/apis/shield-service-create-organization/index.html index ca09c6ba1..909db6b9c 100644 --- a/apis/shield-service-create-organization/index.html +++ b/apis/shield-service-create-organization/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Create organization​

Create organization

Request Body required
    name string required

    The name of the organization. The name must be unique within the entire Shield instance. The name can contain only alphanumeric characters, dashes and underscores.
    Example:"shield-org1-acme"

    title string

    The title can contain any UTF-8 character, used to provide a human-readable name for the organization. Can also be left empty.
    Example: "Acme Inc"

    metadata object

    Metadata object for organizations that can hold key value pairs defined in Organization Metaschema. The metadata object can be used to store arbitrary information about the organization such as labels, descriptions etc. The default Organization Metaschema contains labels and descripton fields. Update the Organization Metaschema to add more fields.
    Example:{"labels": {"key": "value"}, "description": "Organization description"}

Responses

A successful response.

Schema
    organization object
    id string
    name string
    title string
    metadata object
    createdAt date-time

    The time the organization was created.

    updatedAt date-time

    The time the organization was last updated.

Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-create-policy/index.html b/apis/shield-service-create-policy/index.html index 2f36f6fde..9190e291d 100644 --- a/apis/shield-service-create-policy/index.html +++ b/apis/shield-service-create-policy/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Create policy​

Creates a policy

Request Body required
    roleId string required

    unique id of the role to which policy is assigned

    title string

    The title can contain any UTF-8 character, used to provide a human-readable name for the policy. Can also be left empty.
    Example: Policy title

    resource string required

    The resource to which policy is assigned in this format namespace:uuid.
    Example: app/guardian:70f69c3a-334b-4f25-90b8-4d4f3be6b8e2

    principal string required

    principal is the user or group to which policy is assigned. The principal id must be prefixed with its namespace id in this format namespace:uuid. The namespace can be app/user, app/group or app/serviceuser (coming up!) and uuid is the unique id of the principal.
    Example: app/user:92f69c3a-334b-4f25-90b8-4d4f3be6b825

    metadata object

    Metadata object for policies that can hold key value pairs defined in Policy Metaschema.
    Example: {"labels": {"key": "value"}, "description": "Policy description"}

Responses

A successful response.

Schema
    policy object
    id string
    title string
    createdAt date-time

    The time the policy was created.

    updatedAt date-time

    The time the policy was last updated.

    roleId string
    resource namespace:uuid
    principal namespace:uuid
    metadata object
Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-create-project-resource/index.html b/apis/shield-service-create-project-resource/index.html index 1957b0103..47c883d29 100644 --- a/apis/shield-service-create-project-resource/index.html +++ b/apis/shield-service-create-project-resource/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Create resource​

Creates a resource in a project

Path Parameters
    projectId string required

    project uuid or name

Query Parameters
    id string

    Autogenerated if skipped.

Request Body required
    name string required

    The name of the resource. Must be unique within the project.
    Example: my-resource

    title string

    The title can contain any UTF-8 character, used to provide a human-readable name for the resource. Can also be left empty.

    namespace string required

    The namespace of the resource. The resource namespace are created when permissions for that resource is created in Shield. If namespace doesn't exists the request will fail.
    Example: compute/instance

    principal format namespace:uuid or just uuid for user

    UserID or ServiceUserID that should be marked as owner of the resource. If not provided, the current logged in user will be made the resource owner.
    Example: user:92f69c3a-334b-4f25-90b8-4d4f3be6b825

    metadata object
Responses

A successful response.

Schema
    resource object
    id string
    name string

    Name of the resource. Must be unique within the project.

    createdAt date-time

    The time the resource was created.

    updatedAt date-time

    The time the resource was last updated.

    urn string
    projectId string
    namespace string
    principal string
    metadata object
Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-create-project/index.html b/apis/shield-service-create-project/index.html index b193ac337..91885f5a2 100644 --- a/apis/shield-service-create-project/index.html +++ b/apis/shield-service-create-project/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Create project​

Create project

Request Body required
    name string required

    The name of the project. The name must be unique within the entire Shield instance. The name can contain only alphanumeric characters, dashes and underscores.
    Example: shield-playground

    title string

    The title can contain any UTF-8 character, used to provide a human-readable name for the project. Can also be left empty.
    Example: Shield Playground

    metadata object

    Metadata object for projects that can hold key value pairs defined in Project Metaschema.

    orgId string required

    unique id of the organization to which project belongs

Responses

A successful response.

Schema
    project object
    id string
    name string
    title string
    orgId string
    metadata object
    createdAt date-time

    The time the project was created.

    updatedAt date-time

    The time the project was last updated.

Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-create-relation/index.html b/apis/shield-service-create-relation/index.html index 670083d90..a482a8bd1 100644 --- a/apis/shield-service-create-relation/index.html +++ b/apis/shield-service-create-relation/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Create relation​

Create relation

Request Body required
    object objectnamespace:uuid
    subject subjectnamespace:uuid
    relation string
    subjectSubRelation string
Responses

A successful response.

Schema
    relation object
    id string
    createdAt date-time

    The time the relation was created.

    updatedAt date-time

    The time the relation was last updated.

    subjectSubRelation string
    relation string
    object objectnamespace:id
    subject subjectnamespace:id
Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-create-service-user-key/index.html b/apis/shield-service-create-service-user-key/index.html index f2903d64e..1c2d53fd3 100644 --- a/apis/shield-service-create-service-user-key/index.html +++ b/apis/shield-service-create-service-user-key/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Create service user key​

Generate a service user key and return it, the private key part of the response will not be persisted and should be kept securely by client.

Path Parameters
    id string required

    The unique ID of the service user to create a key for.

Request Body required
    title string
Responses

A successful response.

Schema
    key object
    type string
    kid string
    principalId string
    privateKey RSA private key as string
Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-create-service-user-secret/index.html b/apis/shield-service-create-service-user-secret/index.html index 5083c135e..5ca9a41df 100644 --- a/apis/shield-service-create-service-user-secret/index.html +++ b/apis/shield-service-create-service-user-secret/index.html @@ -7,14 +7,14 @@ - +
Skip to main content

Create service user secret​

Generate a service user secret and return it. The secret value will not be persisted and should be securely stored by client.

Path Parameters
    id string required

    The unique ID of the service user to create a key for.

Request Body required
    title string
Responses

A successful response.

Schema
    secret object
    id string
    title string
    secret secret will only be returned once as part of the create process this value is never persisted in the system so if lost, can't be recovered
    createdAt date-time

    The time when the secret was created.

Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-create-service-user/index.html b/apis/shield-service-create-service-user/index.html index 738b1430f..c1ec906d9 100644 --- a/apis/shield-service-create-service-user/index.html +++ b/apis/shield-service-create-service-user/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Create service user​

Create a service user.

Request Body required
    body object
    title string

    User friendly name of the service user.

    metadata object
    orgId string required

    The organization ID to which the service user belongs to.

Responses

A successful response.

Schema
    serviceuser object
    id string
    title string

    User friendly name of the service user.

    metadata object
    createdAt date-time

    The time the user was created.

    updatedAt date-time

    The time the user was last updated.

    state string
    orgId string
Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-create-user/index.html b/apis/shield-service-create-user/index.html index 9dbb20ec1..b6891097e 100644 --- a/apis/shield-service-create-user/index.html +++ b/apis/shield-service-create-user/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Create user​

Create a user with the given details. A user is not attached to an organization or a group by default,and can be invited to the org/group. The name of the user must be unique within the entire Shield instance. If a user name is not provided, Shield automatically generates a name from the user email. The user metadata is validated against the user metaschema. By default the user metaschema contains labels and descriptions for the user. The title field can be optionally added for a user-friendly name.

Example:{"email":"john.doe@raystack.org","title":"John Doe",metadata:{"label": {"key1": "value1"}, "description": "User Description"}}

Request Body required
    name string

    The name of the user. The name must be unique within the entire Shield instance. The name can contain only alphanumeric characters, dashes and underscores and must start with a letter. If not provided, Shield automatically generates a name from the user email.

    email string required

    The email of the user. The email must be unique within the entire Shield instance.
    Example:"john.doe@raystack.org"

    metadata object

    Metadata object for users that can hold key value pairs pre-defined in User Metaschema. The metadata object can be used to store arbitrary information about the user such as label, description etc. By default the user metaschema contains labels and descriptions for the user. Update the same to add more fields to the user metadata object.
    Example:{"label": {"key1": "value1"}, "description": "User Description"}

    title string

    The title can contain any UTF-8 character, used to provide a human-readable name for the user. Can also be left empty.
    Example:"John Doe"

Responses

A successful response.

Schema
    user object
    id string
    name can either be empty or must start with a character

    Unique name of the user.

    title string

    Name of the user.

    email string
    metadata object
    createdAt date-time

    The time the user was created.

    updatedAt date-time

    The time the user was last updated.

    state string
Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-delete-group/index.html b/apis/shield-service-delete-group/index.html index 8505f14a1..2b73ec160 100644 --- a/apis/shield-service-delete-group/index.html +++ b/apis/shield-service-delete-group/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Delete group​

Delete an organization group permanently and all of its relations

Path Parameters
    orgId string required
    id string required
Responses

A successful response.

Schema

    object

Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-delete-meta-schema/index.html b/apis/shield-service-delete-meta-schema/index.html index cf3db09c1..285e92e3b 100644 --- a/apis/shield-service-delete-meta-schema/index.html +++ b/apis/shield-service-delete-meta-schema/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Delete metaschema​

Delete a metadata schema permanently. Once deleted the metaschema won't be used to validate the metadata. For example, if a metaschema(with label and description fields) is used to validate the metadata of a user, then deleting the metaschema will not validate the metadata of the user and metadata field can contain any key-value pair(and say another field called foo can be inserted in a user's metadata).

Path Parameters
    id string required
Responses

A successful response.

Schema

    object

Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-delete-organization-invitation/index.html b/apis/shield-service-delete-organization-invitation/index.html index 16e4b6361..ded378b4a 100644 --- a/apis/shield-service-delete-organization-invitation/index.html +++ b/apis/shield-service-delete-organization-invitation/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Delete pending invitation​

Delete a pending invitation queued for an organization

Path Parameters
    orgId string required
    id string required
Responses

A successful response.

Schema

    object

Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-delete-organization-role/index.html b/apis/shield-service-delete-organization-role/index.html index 1e94c4bd4..29ac322de 100644 --- a/apis/shield-service-delete-organization-role/index.html +++ b/apis/shield-service-delete-organization-role/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Delete organization role​

Delete a custom role and all of its relations under an organization permanently.

Path Parameters
    orgId string required
    id string required
Responses

A successful response.

Schema

    object

Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-delete-organization/index.html b/apis/shield-service-delete-organization/index.html index 9c1dd56cf..7a3ab2b16 100644 --- a/apis/shield-service-delete-organization/index.html +++ b/apis/shield-service-delete-organization/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Delete organization​

Delete an organization and all of its relations permanently. The organization users will not be deleted from Shield.

Path Parameters
    id string required
Responses

A successful response.

Schema

    object

Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-delete-policy/index.html b/apis/shield-service-delete-policy/index.html index 724be0585..70ba9b03d 100644 --- a/apis/shield-service-delete-policy/index.html +++ b/apis/shield-service-delete-policy/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Delete Policy​

Delete a policy all of its relations permanently.

Path Parameters
    id string required
Responses

A successful response.

Schema

    object

Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-delete-project-resource/index.html b/apis/shield-service-delete-project-resource/index.html index 21bf9a72b..2c17d1c50 100644 --- a/apis/shield-service-delete-project-resource/index.html +++ b/apis/shield-service-delete-project-resource/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Delete resource​

Deletes a resource from a project permanently

Path Parameters
    projectId string required
    id string required
Responses

A successful response.

Schema

    object

Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-delete-project/index.html b/apis/shield-service-delete-project/index.html index 25236c01b..f37b2fce6 100644 --- a/apis/shield-service-delete-project/index.html +++ b/apis/shield-service-delete-project/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Delete Project​

Delete a project all of its relations permanently.

Path Parameters
    id string required
Responses

A successful response.

Schema

    object

Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-delete-relation/index.html b/apis/shield-service-delete-relation/index.html index fc560f70f..3f18d23f1 100644 --- a/apis/shield-service-delete-relation/index.html +++ b/apis/shield-service-delete-relation/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Delete relation​

Remove a subject having a relation from an object

Path Parameters
    relation string required
    object string required

    objectnamespace:uuid

    subject string required

    subjectnamespace:uuid

Responses

A successful response.

Schema

    object

Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-delete-service-user-key/index.html b/apis/shield-service-delete-service-user-key/index.html index 808302cf8..be3c6adbf 100644 --- a/apis/shield-service-delete-service-user-key/index.html +++ b/apis/shield-service-delete-service-user-key/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Delete service user key​

Delete a service user key permanently.

Path Parameters
    id string required

    The unique ID of the service user to delete a key for.

    keyId string required

    The unique ID of the key to delete.

Responses

A successful response.

Schema

    object

Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-delete-service-user-secret/index.html b/apis/shield-service-delete-service-user-secret/index.html index 68752a557..955ec31af 100644 --- a/apis/shield-service-delete-service-user-secret/index.html +++ b/apis/shield-service-delete-service-user-secret/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Delete service user secret​

Delete a service user secret credential.

Path Parameters
    id string required

    The unique ID of the service user to delete a secret for.

    secretId string required

    The unique ID of the secret to delete.

Responses

A successful response.

Schema

    object

Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-delete-service-user/index.html b/apis/shield-service-delete-service-user/index.html index cda121043..009d37e25 100644 --- a/apis/shield-service-delete-service-user/index.html +++ b/apis/shield-service-delete-service-user/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Delete service user​

Delete a service user permanently and all of its relations (keys, organizations, roles, etc)

Path Parameters
    id string required

    The unique ID of the service user to delete.

Responses

A successful response.

Schema

    object

Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-delete-user/index.html b/apis/shield-service-delete-user/index.html index e8e24430c..0609a5d94 100644 --- a/apis/shield-service-delete-user/index.html +++ b/apis/shield-service-delete-user/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Delete user​

Delete an user permanently forever and all of its relations (organizations, groups, etc)

Path Parameters
    id string required
Responses

A successful response.

Schema

    object

Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-disable-group/index.html b/apis/shield-service-disable-group/index.html index b3911422f..a55dfe624 100644 --- a/apis/shield-service-disable-group/index.html +++ b/apis/shield-service-disable-group/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Disable group​

Sets the state of the group as disabled. The group will not be available for access control and the existing users in the group will not be able to access any resources that are assigned to the group. No other users can be added to the group while it is disabled.

Path Parameters
    orgId string required
    id string required
Request Body required

    object

Responses

A successful response.

Schema

    object

Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-disable-organization/index.html b/apis/shield-service-disable-organization/index.html index c0458b2a0..079c335bb 100644 --- a/apis/shield-service-disable-organization/index.html +++ b/apis/shield-service-disable-organization/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Disable organization​

Sets the state of the organization as disabled. The existing users in the org will not be able to access any organization resources.

Path Parameters
    id string required
Request Body required

    object

Responses

A successful response.

Schema

    object

Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-disable-project/index.html b/apis/shield-service-disable-project/index.html index 3d0a04b35..cde7308dd 100644 --- a/apis/shield-service-disable-project/index.html +++ b/apis/shield-service-disable-project/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Disable project​

Disable project

Path Parameters
    id string required
Request Body required

    object

Responses

A successful response.

Schema

    object

Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-disable-user/index.html b/apis/shield-service-disable-user/index.html index cf6fd57d2..24fb2421c 100644 --- a/apis/shield-service-disable-user/index.html +++ b/apis/shield-service-disable-user/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Disable user​

Sets the state of the user as diabled.The user's membership to groups and organizations will still exist along with all it's roles for access control, but the user will not be able to log in and access the Shield instance.

Path Parameters
    id string required
Request Body required

    object

Responses

A successful response.

Schema

    object

Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-enable-group/index.html b/apis/shield-service-enable-group/index.html index 0a290bccf..b47708ab7 100644 --- a/apis/shield-service-enable-group/index.html +++ b/apis/shield-service-enable-group/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Enable group​

Sets the state of the group as enabled. The enabled flag is used to determine if the group can be used for access control.

Path Parameters
    orgId string required
    id string required
Request Body required

    object

Responses

A successful response.

Schema

    object

Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-enable-organization/index.html b/apis/shield-service-enable-organization/index.html index ed3bb76d0..b27c41116 100644 --- a/apis/shield-service-enable-organization/index.html +++ b/apis/shield-service-enable-organization/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Enable organization​

Sets the state of the organization as enabled. The existing users in the org will be able to access any organization resources.

Path Parameters
    id string required
Request Body required

    object

Responses

A successful response.

Schema

    object

Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-enable-project/index.html b/apis/shield-service-enable-project/index.html index 6966bb6a5..e9cfc65a8 100644 --- a/apis/shield-service-enable-project/index.html +++ b/apis/shield-service-enable-project/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Enable project​

Enable project

Path Parameters
    id string required
Request Body required

    object

Responses

A successful response.

Schema

    object

Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-enable-user/index.html b/apis/shield-service-enable-user/index.html index 2684b96c6..0a044a59f 100644 --- a/apis/shield-service-enable-user/index.html +++ b/apis/shield-service-enable-user/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Enable user​

Sets the state of the user as enabled. The user will be able to log in and access the Shield instance.

Path Parameters
    id string required
Request Body required

    object

Responses

A successful response.

Schema

    object

Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-get-current-user/index.html b/apis/shield-service-get-current-user/index.html index 5de8d613c..a55e60a2e 100644 --- a/apis/shield-service-get-current-user/index.html +++ b/apis/shield-service-get-current-user/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Get current user​

Get current user

Responses

A successful response.

Schema
    user object
    id string
    name can either be empty or must start with a character

    Unique name of the user.

    title string

    Name of the user.

    email string
    metadata object
    createdAt date-time

    The time the user was created.

    updatedAt date-time

    The time the user was last updated.

    state string
    serviceuser object
    id string
    title string

    User friendly name of the service user.

    metadata object
    createdAt date-time

    The time the user was created.

    updatedAt date-time

    The time the user was last updated.

    state string
    orgId string
Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-get-group/index.html b/apis/shield-service-get-group/index.html index e30f6fa9b..4bda4772f 100644 --- a/apis/shield-service-get-group/index.html +++ b/apis/shield-service-get-group/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Get group​

Get group

Path Parameters
    orgId string required
    id string required
Responses

A successful response.

Schema
    group object
    id string
    name string
    title string
    orgId string
    metadata object
    createdAt date-time

    The time the group was created.

    updatedAt date-time

    The time the group was last updated.

Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-get-jw-ks-2/index.html b/apis/shield-service-get-jw-ks-2/index.html index 3dc8f6883..ae16c5f7b 100644 --- a/apis/shield-service-get-jw-ks-2/index.html +++ b/apis/shield-service-get-jw-ks-2/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Get well known JWKs​

Get well known JWKs

Responses

A successful response.

Schema
    keys object[]
  • Array [
    • kty string

    Key Type.

    alg string

    Algorithm.

    use string

    Permitted uses for the public keys.

    kid string

    Key ID.

    n string

    Used for RSA keys.

    e string

    Used for RSA keys.

    x string

    Used for ECDSA keys.

    y string

    Used for ECDSA keys.

    crv string

    Used for ECDSA keys.

  • ]
Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-get-jw-ks/index.html b/apis/shield-service-get-jw-ks/index.html index 21b782d54..c47dfcb82 100644 --- a/apis/shield-service-get-jw-ks/index.html +++ b/apis/shield-service-get-jw-ks/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Get well known JWKs​

Get well known JWKs

Responses

A successful response.

Schema
    keys object[]
  • Array [
    • kty string

    Key Type.

    alg string

    Algorithm.

    use string

    Permitted uses for the public keys.

    kid string

    Key ID.

    n string

    Used for RSA keys.

    e string

    Used for RSA keys.

    x string

    Used for ECDSA keys.

    y string

    Used for ECDSA keys.

    crv string

    Used for ECDSA keys.

  • ]
Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-get-meta-schema/index.html b/apis/shield-service-get-meta-schema/index.html index 73601ec15..3d8cfcb59 100644 --- a/apis/shield-service-get-meta-schema/index.html +++ b/apis/shield-service-get-meta-schema/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Get metaschema​

Get a metadata schema by ID.

Path Parameters
    id string required
Responses

A successful response.

Schema
    metaschema object
    id string

    The unique metaschema uuid.

    name string
    schema string

    The metaschema json schema.

    createdAt date-time

    The time when the metaschema was created.

    updatedAt date-time

    The time when the metaschema was updated.

Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-get-namespace/index.html b/apis/shield-service-get-namespace/index.html index ac16f234d..bba5dda2b 100644 --- a/apis/shield-service-get-namespace/index.html +++ b/apis/shield-service-get-namespace/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Get namespace​

Returns a namespace by ID

Path Parameters
    id string required
Responses

A successful response.

Schema
    namespace object
    id string
    name name could be in a format like: app/organization
    metadata object
    createdAt date-time

    The time the namespace was created.

    updatedAt date-time

    The time the namespace was last updated.

Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-get-organization-invitation/index.html b/apis/shield-service-get-organization-invitation/index.html index 691a58835..5ca75146a 100644 --- a/apis/shield-service-get-organization-invitation/index.html +++ b/apis/shield-service-get-organization-invitation/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Get pending invitation​

Returns a pending invitation queued for an organization

Path Parameters
    orgId string required
    id string required
Responses

A successful response.

Schema
    invitation object
    id string

    The unique invitation identifier.

    userId string

    The user email of the invited user.

    orgId string

    The organization id to which the user is invited.

    groupIds string[]

    The list of group ids to which the user is invited.

    metadata object

    The metadata of the invitation.

    createdAt date-time

    The time when the invitation was created.

    expiresAt date-time

    The time when the invitation expires.

Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-get-organization-role/index.html b/apis/shield-service-get-organization-role/index.html index b86ff92be..4c6cb6f3f 100644 --- a/apis/shield-service-get-organization-role/index.html +++ b/apis/shield-service-get-organization-role/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Get organization role​

Returns a custom role under an organization along with its associated permissions

Path Parameters
    orgId string required
    id string required
Responses

A successful response.

Schema
    role object
    id string
    name string
    permissions string[]
    title string
    metadata object
    createdAt date-time

    The time the role was created.

    updatedAt date-time

    The time the role was last updated.

    orgId string
    state string
Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-get-organization/index.html b/apis/shield-service-get-organization/index.html index a361de19b..166aa9d37 100644 --- a/apis/shield-service-get-organization/index.html +++ b/apis/shield-service-get-organization/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Get organization​

Get organization by ID or name

Path Parameters
    id string required
Responses

A successful response.

Schema
    organization object
    id string
    name string
    title string
    metadata object
    createdAt date-time

    The time the organization was created.

    updatedAt date-time

    The time the organization was last updated.

Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-get-organizations-by-current-user/index.html b/apis/shield-service-get-organizations-by-current-user/index.html index 64b5fe86f..3b49eed69 100644 --- a/apis/shield-service-get-organizations-by-current-user/index.html +++ b/apis/shield-service-get-organizations-by-current-user/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Get my organizations​

Get all organizations the current user belongs to

Responses

A successful response.

Schema
    organizations object[]
  • Array [
    • id string
    name string
    title string
    metadata object
    createdAt date-time

    The time the organization was created.

    updatedAt date-time

    The time the organization was last updated.

  • ]
Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-get-organizations-by-user/index.html b/apis/shield-service-get-organizations-by-user/index.html index 998fb4bc8..d169fae05 100644 --- a/apis/shield-service-get-organizations-by-user/index.html +++ b/apis/shield-service-get-organizations-by-user/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Get user organizations​

Get all the organizations a user belongs to.

Path Parameters
    id string required
Responses

A successful response.

Schema
    organizations object[]
  • Array [
    • id string
    name string
    title string
    metadata object
    createdAt date-time

    The time the organization was created.

    updatedAt date-time

    The time the organization was last updated.

  • ]
Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-get-permission/index.html b/apis/shield-service-get-permission/index.html index ddc9cd28b..f7d26e92f 100644 --- a/apis/shield-service-get-permission/index.html +++ b/apis/shield-service-get-permission/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Get permission​

Returns a permission by ID

Path Parameters
    id string required
Responses

A successful response.

Schema
    permission object
    id string
    name string
    title string
    createdAt date-time

    The time the permission was created.

    updatedAt date-time

    The time the permission was last updated.

    namespace string
    metadata object
    key string

    Permission path key is composed of three parts, 'service.resource.verb'. Where 'service.resource' works as a namespace for the 'verb'.

Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-get-policy/index.html b/apis/shield-service-get-policy/index.html index 6aba5ba0a..f561ee82a 100644 --- a/apis/shield-service-get-policy/index.html +++ b/apis/shield-service-get-policy/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Get policy​

Returns a policy by ID

Path Parameters
    id string required
Responses

A successful response.

Schema
    policy object
    id string
    title string
    createdAt date-time

    The time the policy was created.

    updatedAt date-time

    The time the policy was last updated.

    roleId string
    resource namespace:uuid
    principal namespace:uuid
    metadata object
Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-get-project-resource/index.html b/apis/shield-service-get-project-resource/index.html index 74e90b13d..d89b957a4 100644 --- a/apis/shield-service-get-project-resource/index.html +++ b/apis/shield-service-get-project-resource/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Get resource​

Returns a project resource by ID

Path Parameters
    projectId string required
    id string required
Responses

A successful response.

Schema
    resource object
    id string
    name string

    Name of the resource. Must be unique within the project.

    createdAt date-time

    The time the resource was created.

    updatedAt date-time

    The time the resource was last updated.

    urn string
    projectId string
    namespace string
    principal string
    metadata object
Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-get-project/index.html b/apis/shield-service-get-project/index.html index 506f6dee5..14c575558 100644 --- a/apis/shield-service-get-project/index.html +++ b/apis/shield-service-get-project/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Get project​

Returns a project by ID

Path Parameters
    id string required
Responses

A successful response.

Schema
    project object
    id string
    name string
    title string
    orgId string
    metadata object
    createdAt date-time

    The time the project was created.

    updatedAt date-time

    The time the project was last updated.

Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-get-relation/index.html b/apis/shield-service-get-relation/index.html index ccf081e10..24a1443d1 100644 --- a/apis/shield-service-get-relation/index.html +++ b/apis/shield-service-get-relation/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Get relation​

Returns a relation by ID

Path Parameters
    id string required
Responses

A successful response.

Schema
    relation object
    id string
    createdAt date-time

    The time the relation was created.

    updatedAt date-time

    The time the relation was last updated.

    subjectSubRelation string
    relation string
    object objectnamespace:id
    subject subjectnamespace:id
Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-get-service-user-key/index.html b/apis/shield-service-get-service-user-key/index.html index 192727f6f..d7f1a3c92 100644 --- a/apis/shield-service-get-service-user-key/index.html +++ b/apis/shield-service-get-service-user-key/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Get service user key​

Get a service user public RSA JWK set.

Path Parameters
    id string required

    The unique ID of the service user to get a key for.

    keyId string required

    The unique ID of the key to get.

Responses

A successful response.

Schema
    keys object[]
  • Array [
    • kty string

    Key Type.

    alg string

    Algorithm.

    use string

    Permitted uses for the public keys.

    kid string

    Key ID.

    n string

    Used for RSA keys.

    e string

    Used for RSA keys.

    x string

    Used for ECDSA keys.

    y string

    Used for ECDSA keys.

    crv string

    Used for ECDSA keys.

  • ]
Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-get-service-user/index.html b/apis/shield-service-get-service-user/index.html index 3d02cbaf0..40e32843a 100644 --- a/apis/shield-service-get-service-user/index.html +++ b/apis/shield-service-get-service-user/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Get service user​

Get service user details by its id.

Path Parameters
    id string required

    The unique ID of the service user to get.

Responses

A successful response.

Schema
    serviceuser object
    id string
    title string

    User friendly name of the service user.

    metadata object
    createdAt date-time

    The time the user was created.

    updatedAt date-time

    The time the user was last updated.

    state string
    orgId string
Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-get-user/index.html b/apis/shield-service-get-user/index.html index 73355100f..2244ab724 100644 --- a/apis/shield-service-get-user/index.html +++ b/apis/shield-service-get-user/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Get user​

Get a user by id searched over all organizations in Shield.

Path Parameters
    id string required
Responses

A successful response.

Schema
    user object
    id string
    name can either be empty or must start with a character

    Unique name of the user.

    title string

    Name of the user.

    email string
    metadata object
    createdAt date-time

    The time the user was created.

    updatedAt date-time

    The time the user was last updated.

    state string
Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-list-auth-strategies/index.html b/apis/shield-service-list-auth-strategies/index.html index 8ee4fc386..d8f10c23d 100644 --- a/apis/shield-service-list-auth-strategies/index.html +++ b/apis/shield-service-list-auth-strategies/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

List authentication strategies​

Returns a list of identity providers configured on an instance level in Shield. e.g Google, AzureAD, Github etc

Responses

A successful response.

Schema
    strategies object[]
  • Array [
    • name string
    params object
  • ]
Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-list-current-user-groups/index.html b/apis/shield-service-list-current-user-groups/index.html index f447c3470..5becaea38 100644 --- a/apis/shield-service-list-current-user-groups/index.html +++ b/apis/shield-service-list-current-user-groups/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

List my groups​

List my groups

Responses

A successful response.

Schema
    groups object[]
  • Array [
    • id string
    name string
    title string
    orgId string
    metadata object
    createdAt date-time

    The time the group was created.

    updatedAt date-time

    The time the group was last updated.

  • ]
Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-list-group-users/index.html b/apis/shield-service-list-group-users/index.html index e5b8c7ce1..39c032184 100644 --- a/apis/shield-service-list-group-users/index.html +++ b/apis/shield-service-list-group-users/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

List group users​

Returns a list of users that belong to a group.

Path Parameters
    orgId string required
    id string required
Responses

A successful response.

Schema
    users object[]
  • Array [
    • id string
    name can either be empty or must start with a character

    Unique name of the user.

    title string

    Name of the user.

    email string
    metadata object
    createdAt date-time

    The time the user was created.

    updatedAt date-time

    The time the user was last updated.

    state string
  • ]
Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-list-meta-schemas/index.html b/apis/shield-service-list-meta-schemas/index.html index 21ca01463..bc7ac1763 100644 --- a/apis/shield-service-list-meta-schemas/index.html +++ b/apis/shield-service-list-meta-schemas/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

List metaschemas​

Returns a list of all metaschemas configured on an instance level in Shield. e.g user, project, organization etc

Responses

A successful response.

Schema
    metaschemas object[]
  • Array [
    • id string

    The unique metaschema uuid.

    name string
    schema string

    The metaschema json schema.

    createdAt date-time

    The time when the metaschema was created.

    updatedAt date-time

    The time when the metaschema was updated.

  • ]
Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-list-namespaces/index.html b/apis/shield-service-list-namespaces/index.html index 41fef2eb4..a9888e5c6 100644 --- a/apis/shield-service-list-namespaces/index.html +++ b/apis/shield-service-list-namespaces/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Get all namespaces​

Returns the list of all namespaces in a Shield instance

Responses

A successful response.

Schema
    namespaces object[]
  • Array [
    • id string
    name name could be in a format like: app/organization
    metadata object
    createdAt date-time

    The time the namespace was created.

    updatedAt date-time

    The time the namespace was last updated.

  • ]
Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-list-organization-admins/index.html b/apis/shield-service-list-organization-admins/index.html index 38932a59b..f37516355 100644 --- a/apis/shield-service-list-organization-admins/index.html +++ b/apis/shield-service-list-organization-admins/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

List organization admins​

Returns a list admins of an organization

Path Parameters
    id string required
Responses

A successful response.

Schema
    users object[]
  • Array [
    • id string
    name can either be empty or must start with a character

    Unique name of the user.

    title string

    Name of the user.

    email string
    metadata object
    createdAt date-time

    The time the user was created.

    updatedAt date-time

    The time the user was last updated.

    state string
  • ]
Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-list-organization-groups/index.html b/apis/shield-service-list-organization-groups/index.html index 8311e80b9..0ae7892f0 100644 --- a/apis/shield-service-list-organization-groups/index.html +++ b/apis/shield-service-list-organization-groups/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

List organization groups​

Get all groups that belong to an organization. The results can be filtered by state which can be either be enabled or disabled.

Path Parameters
    orgId string required
Query Parameters
    state string

    The state of the group to filter by. It can be enabled or disabled.

Responses

A successful response.

Schema
    groups object[]
  • Array [
    • id string
    name string
    title string
    orgId string
    metadata object
    createdAt date-time

    The time the group was created.

    updatedAt date-time

    The time the group was last updated.

  • ]
Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-list-organization-invitations/index.html b/apis/shield-service-list-organization-invitations/index.html index decb2b51f..cf0d6be5f 100644 --- a/apis/shield-service-list-organization-invitations/index.html +++ b/apis/shield-service-list-organization-invitations/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

List pending invitations​

Returns all pending invitations queued for an organization

Path Parameters
    orgId string required

    unique id of the organization to which user is invited

Query Parameters
    userId string

    user_id filter is the email id of user who are invited inside the organization.

Responses

A successful response.

Schema
    invitations object[]
  • Array [
    • id string

    The unique invitation identifier.

    userId string

    The user email of the invited user.

    orgId string

    The organization id to which the user is invited.

    groupIds string[]

    The list of group ids to which the user is invited.

    metadata object

    The metadata of the invitation.

    createdAt date-time

    The time when the invitation was created.

    expiresAt date-time

    The time when the invitation expires.

  • ]
Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-list-organization-projects/index.html b/apis/shield-service-list-organization-projects/index.html index 2da49bddd..91a9cbe21 100644 --- a/apis/shield-service-list-organization-projects/index.html +++ b/apis/shield-service-list-organization-projects/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Get organization projects​

Get all projects that belong to an organization

Path Parameters
    id string required
Query Parameters
    state string

    Filter projects by state. If not specified, all projects are returned.
    Possible values: enabled or disabled

Responses

A successful response.

Schema
    projects object[]
  • Array [
    • id string
    name string
    title string
    orgId string
    metadata object
    createdAt date-time

    The time the project was created.

    updatedAt date-time

    The time the project was last updated.

  • ]
Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-list-organization-roles/index.html b/apis/shield-service-list-organization-roles/index.html index 31732821c..493e6dc2f 100644 --- a/apis/shield-service-list-organization-roles/index.html +++ b/apis/shield-service-list-organization-roles/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

List organization roles​

Returns a list of custom roles created under an organization with their associated permissions

Path Parameters
    orgId string required
Query Parameters
    state string
Responses

A successful response.

Schema
    roles object[]
  • Array [
    • id string
    name string
    permissions string[]
    title string
    metadata object
    createdAt date-time

    The time the role was created.

    updatedAt date-time

    The time the role was last updated.

    orgId string
    state string
  • ]
Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-list-organization-service-users/index.html b/apis/shield-service-list-organization-service-users/index.html index 5d2dcb4ca..9ad6a733b 100644 --- a/apis/shield-service-list-organization-service-users/index.html +++ b/apis/shield-service-list-organization-service-users/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

List organization service users​

List organization service users

Path Parameters
    id string required
Responses

A successful response.

Schema
    serviceusers object[]
  • Array [
    • id string
    title string

    User friendly name of the service user.

    metadata object
    createdAt date-time

    The time the user was created.

    updatedAt date-time

    The time the user was last updated.

    state string
    orgId string
  • ]
Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-list-organization-users/index.html b/apis/shield-service-list-organization-users/index.html index 87aa6a590..8fc2dfb19 100644 --- a/apis/shield-service-list-organization-users/index.html +++ b/apis/shield-service-list-organization-users/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

List organization users​

List organization users

Path Parameters
    id string required
Query Parameters
    permissionFilter string
Responses

A successful response.

Schema
    users object[]
  • Array [
    • id string
    name can either be empty or must start with a character

    Unique name of the user.

    title string

    Name of the user.

    email string
    metadata object
    createdAt date-time

    The time the user was created.

    updatedAt date-time

    The time the user was last updated.

    state string
  • ]
Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-list-organizations/index.html b/apis/shield-service-list-organizations/index.html index 704a220fe..1d0f5a33c 100644 --- a/apis/shield-service-list-organizations/index.html +++ b/apis/shield-service-list-organizations/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

List organizations​

Returns a list of organizations. It can be filtered by userID or organization state.

Query Parameters
    userId string

    The user ID to filter by. It can be used to list all the organizations that the user is a member of. Otherwise, all the organizations in the Shield instance will be listed.

    state string

    The state to filter by. It can be enabled or disabled.

Responses

A successful response.

Schema
    organizations object[]
  • Array [
    • id string
    name string
    title string
    metadata object
    createdAt date-time

    The time the organization was created.

    updatedAt date-time

    The time the organization was last updated.

  • ]
Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-list-permissions/index.html b/apis/shield-service-list-permissions/index.html index 458131ece..99125cf96 100644 --- a/apis/shield-service-list-permissions/index.html +++ b/apis/shield-service-list-permissions/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Get all permissions​

Get all permissions

Responses

A successful response.

Schema
    permissions object[]
  • Array [
    • id string
    name string
    title string
    createdAt date-time

    The time the permission was created.

    updatedAt date-time

    The time the permission was last updated.

    namespace string
    metadata object
    key string

    Permission path key is composed of three parts, 'service.resource.verb'. Where 'service.resource' works as a namespace for the 'verb'.

  • ]
Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-list-project-admins/index.html b/apis/shield-service-list-project-admins/index.html index 06c0833f6..946f7ab17 100644 --- a/apis/shield-service-list-project-admins/index.html +++ b/apis/shield-service-list-project-admins/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

List project admins​

Returns a collection of admins of a project

Path Parameters
    id string required
Responses

A successful response.

Schema
    users object[]
  • Array [
    • id string
    name can either be empty or must start with a character

    Unique name of the user.

    title string

    Name of the user.

    email string
    metadata object
    createdAt date-time

    The time the user was created.

    updatedAt date-time

    The time the user was last updated.

    state string
  • ]
Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-list-project-resources/index.html b/apis/shield-service-list-project-resources/index.html index 55d08edbf..d4a0035c2 100644 --- a/apis/shield-service-list-project-resources/index.html +++ b/apis/shield-service-list-project-resources/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Get all resources​

Get all resources

Path Parameters
    projectId string required
Query Parameters
    namespace string
Responses

A successful response.

Schema
    resources object[]
  • Array [
    • id string
    name string

    Name of the resource. Must be unique within the project.

    createdAt date-time

    The time the resource was created.

    updatedAt date-time

    The time the resource was last updated.

    urn string
    projectId string
    namespace string
    principal string
    metadata object
  • ]
Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-list-project-users/index.html b/apis/shield-service-list-project-users/index.html index 079277501..0fb8771a4 100644 --- a/apis/shield-service-list-project-users/index.html +++ b/apis/shield-service-list-project-users/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

List project users​

Returns a collection of users of a project. Filter by user permissions is supported.

Path Parameters
    id string required
Query Parameters
    permissionFilter string
Responses

A successful response.

Schema
    users object[]
  • Array [
    • id string
    name can either be empty or must start with a character

    Unique name of the user.

    title string

    Name of the user.

    email string
    metadata object
    createdAt date-time

    The time the user was created.

    updatedAt date-time

    The time the user was last updated.

    state string
  • ]
Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-list-roles/index.html b/apis/shield-service-list-roles/index.html index ad29e4c2b..7263037c3 100644 --- a/apis/shield-service-list-roles/index.html +++ b/apis/shield-service-list-roles/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

List platform roles​

Returns a list of platform wide roles available in enitre Shield instance along with their associated permissions

Query Parameters
    state string
Responses

A successful response.

Schema
    roles object[]
  • Array [
    • id string
    name string
    permissions string[]
    title string
    metadata object
    createdAt date-time

    The time the role was created.

    updatedAt date-time

    The time the role was last updated.

    orgId string
    state string
  • ]
Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-list-service-user-keys/index.html b/apis/shield-service-list-service-user-keys/index.html index 3d574966f..78027e9d3 100644 --- a/apis/shield-service-list-service-user-keys/index.html +++ b/apis/shield-service-list-service-user-keys/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

List service user keys​

List all the keys of a service user with its details except jwk.

Path Parameters
    id string required

    The unique ID of the service user to list keys for.

Responses

A successful response.

Schema
    keys object[]
  • Array [
    • id string
    title string
    principalId string
    publicKey string
    createdAt date-time

    The time when the secret was created.

  • ]
Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-list-service-user-secrets/index.html b/apis/shield-service-list-service-user-secrets/index.html index 69401e878..0e3bb3313 100644 --- a/apis/shield-service-list-service-user-secrets/index.html +++ b/apis/shield-service-list-service-user-secrets/index.html @@ -7,14 +7,14 @@ - +
Skip to main content

List service user secrets​

List all the secrets of a service user.

Path Parameters
    id string required

    The unique ID of the service user to list secrets for.

Responses

A successful response.

Schema
    secrets object[]
  • Array [
    • id string
    title string
    secret secret will only be returned once as part of the create process this value is never persisted in the system so if lost, can't be recovered
    createdAt date-time

    The time when the secret was created.

  • ]
Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-list-service-users/index.html b/apis/shield-service-list-service-users/index.html index a33d4bdb9..df6742aff 100644 --- a/apis/shield-service-list-service-users/index.html +++ b/apis/shield-service-list-service-users/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

List org service users​

Returns the service user of an organization in a Shield instance. It can be filter by it's state

Query Parameters
    orgId string required

    The organization ID to filter service users by.

    state string

    The state to filter by. It can be enabled or disabled.

Responses

A successful response.

Schema
    serviceusers object[]
  • Array [
    • id string
    title string

    User friendly name of the service user.

    metadata object
    createdAt date-time

    The time the user was created.

    updatedAt date-time

    The time the user was last updated.

    state string
    orgId string
  • ]
Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-list-user-groups/index.html b/apis/shield-service-list-user-groups/index.html index 03be1b762..82f4c012c 100644 --- a/apis/shield-service-list-user-groups/index.html +++ b/apis/shield-service-list-user-groups/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

List user groups​

Lists all the groups a user belongs to across all organization in Shield. To get the groups of a user in a specific organization, use the org_id filter in the query parameter.

Path Parameters
    id string required

    The unique ID of the user to get groups for.

Query Parameters
    orgId string

    The organization ID to filter groups by. If not provided, groups from all organizations are returned.

Responses

A successful response.

Schema
    groups object[]
  • Array [
    • id string
    name string
    title string
    orgId string
    metadata object
    createdAt date-time

    The time the group was created.

    updatedAt date-time

    The time the group was last updated.

  • ]
Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-list-user-invitations/index.html b/apis/shield-service-list-user-invitations/index.html index 6830c7903..def7c5762 100644 --- a/apis/shield-service-list-user-invitations/index.html +++ b/apis/shield-service-list-user-invitations/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

List user invitations​

List all the invitations sent to a user.

Path Parameters
    id string required

    The user email to list the invitations for.

Responses

A successful response.

Schema
    invitations object[]
  • Array [
    • id string

    The unique invitation identifier.

    userId string

    The user email of the invited user.

    orgId string

    The organization id to which the user is invited.

    groupIds string[]

    The list of group ids to which the user is invited.

    metadata object

    The metadata of the invitation.

    createdAt date-time

    The time when the invitation was created.

    expiresAt date-time

    The time when the invitation expires.

  • ]
Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-list-users/index.html b/apis/shield-service-list-users/index.html index cdd1cf396..a6c6cfedf 100644 --- a/apis/shield-service-list-users/index.html +++ b/apis/shield-service-list-users/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

List public users​

Returns the users from all the organizations in a Shield instance. It can be filtered by keyword, organization, group and state. Additionally you can include page number and page size for pagination.

Query Parameters
    pageSize int32

    The maximum number of users to return per page. The default is 50.

    pageNum int32

    The page number to return. The default is 1.

    keyword string

    The keyword to search for in name or email.

    orgId string

    The organization ID to filter users by.

    groupId string

    The group id to filter by.

    state string

    The state to filter by. It can be enabled or disabled.

Responses

A successful response.

Schema
    count int32
    users object[]
  • Array [
    • id string
    name can either be empty or must start with a character

    Unique name of the user.

    title string

    Name of the user.

    email string
    metadata object
    createdAt date-time

    The time the user was created.

    updatedAt date-time

    The time the user was last updated.

    state string
  • ]
Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-remove-group-user/index.html b/apis/shield-service-remove-group-user/index.html index 347a0bb11..41f0ad8e1 100644 --- a/apis/shield-service-remove-group-user/index.html +++ b/apis/shield-service-remove-group-user/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Remove group user​

Removes a principle(user and service-users) from a group. If the user is not in the group, the request will succeed but no changes will be made.

Path Parameters
    orgId string required
    id string required
    userId string required
Responses

A successful response.

Schema

    object

Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-remove-organization-user/index.html b/apis/shield-service-remove-organization-user/index.html index 8625c182c..3b509f17e 100644 --- a/apis/shield-service-remove-organization-user/index.html +++ b/apis/shield-service-remove-organization-user/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Remove organization user​

Remove a user from an organization

Path Parameters
    id string required
    userId string required
Responses

A successful response.

Schema

    object

Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-update-current-user/index.html b/apis/shield-service-update-current-user/index.html index 08248beb7..27b9e350f 100644 --- a/apis/shield-service-update-current-user/index.html +++ b/apis/shield-service-update-current-user/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Update current user​

Update current user

Request Body required
    name string

    The name of the user. The name must be unique within the entire Shield instance. The name can contain only alphanumeric characters, dashes and underscores and must start with a letter. If not provided, Shield automatically generates a name from the user email.

    email string required

    The email of the user. The email must be unique within the entire Shield instance.
    Example:"john.doe@raystack.org"

    metadata object

    Metadata object for users that can hold key value pairs pre-defined in User Metaschema. The metadata object can be used to store arbitrary information about the user such as label, description etc. By default the user metaschema contains labels and descriptions for the user. Update the same to add more fields to the user metadata object.
    Example:{"label": {"key1": "value1"}, "description": "User Description"}

    title string

    The title can contain any UTF-8 character, used to provide a human-readable name for the user. Can also be left empty.
    Example:"John Doe"

Responses

A successful response.

Schema
    user object
    id string
    name can either be empty or must start with a character

    Unique name of the user.

    title string

    Name of the user.

    email string
    metadata object
    createdAt date-time

    The time the user was created.

    updatedAt date-time

    The time the user was last updated.

    state string
Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-update-group/index.html b/apis/shield-service-update-group/index.html index c978f660a..22add95f2 100644 --- a/apis/shield-service-update-group/index.html +++ b/apis/shield-service-update-group/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Update group​

Update group

Path Parameters
    orgId string required

    The organization ID to which the group belongs to.

    id string required
Request Body required
    name string required

    The name of the group. The name must be unique within the entire Shield instance. The name can contain only alphanumeric characters, dashes and underscores.

    title string

    The title can contain any UTF-8 character, used to provide a human-readable name for the group. Can also be left empty.

    metadata object

    Metadata object for groups that can hold key value pairs defined in Group Metaschema. The metadata object can be used to store arbitrary information about the group such as labels, descriptions etc. The default Group Metaschema contains labels and descripton fields. Update the Group Metaschema to add more fields.
    Example:{"labels": {"key": "value"}, "description": "Group description"}

Responses

A successful response.

Schema
    group object
    id string
    name string
    title string
    orgId string
    metadata object
    createdAt date-time

    The time the group was created.

    updatedAt date-time

    The time the group was last updated.

Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-update-meta-schema/index.html b/apis/shield-service-update-meta-schema/index.html index a431410b7..1b0f8a33a 100644 --- a/apis/shield-service-update-meta-schema/index.html +++ b/apis/shield-service-update-meta-schema/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Update metaschema​

Update a metadata schema. Only schema field of a metaschema can be updated. The metaschema schema must be a valid JSON schema.Please refer to https://json-schema.org/ to know more about json schema.
Example: {name:"user",schema:{"type":"object","properties":{"label":{"type":"object","additionalProperties":{"type":"string"}},"description":{"type":"string"}}}}

Path Parameters
    id string required
Request Body required
    name string required

    The name of the metaschema. The name must be unique within the entire Shield instance. The name can contain only alphanumeric characters, dashes and underscores.

    schema string required

    The schema of the metaschema. The schema must be a valid JSON schema.Please refer to https://json-schema.org/ to know more about json schema.

Responses

A successful response.

Schema
    metaschema object
    id string

    The unique metaschema uuid.

    name string
    schema string

    The metaschema json schema.

    createdAt date-time

    The time when the metaschema was created.

    updatedAt date-time

    The time when the metaschema was updated.

Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-update-organization-role/index.html b/apis/shield-service-update-organization-role/index.html index ebadcd418..e6784698d 100644 --- a/apis/shield-service-update-organization-role/index.html +++ b/apis/shield-service-update-organization-role/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Update organization role​

Update a custom role under an organization. This custom role will only be available for assignment to the principles within the organization.

Path Parameters
    orgId string required
    id string required
Request Body required
    name string
    permissions string[]
    metadata object
    title string
Responses

A successful response.

Schema
    role object
    id string
    name string
    permissions string[]
    title string
    metadata object
    createdAt date-time

    The time the role was created.

    updatedAt date-time

    The time the role was last updated.

    orgId string
    state string
Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-update-organization/index.html b/apis/shield-service-update-organization/index.html index 5323d9a70..3a021739d 100644 --- a/apis/shield-service-update-organization/index.html +++ b/apis/shield-service-update-organization/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Update organization​

Update organization by ID

Path Parameters
    id string required
Request Body required
    name string required

    The name of the organization. The name must be unique within the entire Shield instance. The name can contain only alphanumeric characters, dashes and underscores.
    Example:"shield-org1-acme"

    title string

    The title can contain any UTF-8 character, used to provide a human-readable name for the organization. Can also be left empty.
    Example: "Acme Inc"

    metadata object

    Metadata object for organizations that can hold key value pairs defined in Organization Metaschema. The metadata object can be used to store arbitrary information about the organization such as labels, descriptions etc. The default Organization Metaschema contains labels and descripton fields. Update the Organization Metaschema to add more fields.
    Example:{"labels": {"key": "value"}, "description": "Organization description"}

Responses

A successful response.

Schema
    organization object
    id string
    name string
    title string
    metadata object
    createdAt date-time

    The time the organization was created.

    updatedAt date-time

    The time the organization was last updated.

Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-update-policy/index.html b/apis/shield-service-update-policy/index.html index 8c2967cd0..c84a1f6a4 100644 --- a/apis/shield-service-update-policy/index.html +++ b/apis/shield-service-update-policy/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Update policy​

Updates a policy by ID

Path Parameters
    id string required
Request Body required
    roleId string required

    unique id of the role to which policy is assigned

    title string

    The title can contain any UTF-8 character, used to provide a human-readable name for the policy. Can also be left empty.
    Example: Policy title

    resource string required

    The resource to which policy is assigned in this format namespace:uuid.
    Example: app/guardian:70f69c3a-334b-4f25-90b8-4d4f3be6b8e2

    principal string required

    principal is the user or group to which policy is assigned. The principal id must be prefixed with its namespace id in this format namespace:uuid. The namespace can be app/user, app/group or app/serviceuser (coming up!) and uuid is the unique id of the principal.
    Example: app/user:92f69c3a-334b-4f25-90b8-4d4f3be6b825

    metadata object

    Metadata object for policies that can hold key value pairs defined in Policy Metaschema.
    Example: {"labels": {"key": "value"}, "description": "Policy description"}

Responses

A successful response.

Schema
    policies object[]
  • Array [
    • id string
    title string
    createdAt date-time

    The time the policy was created.

    updatedAt date-time

    The time the policy was last updated.

    roleId string
    resource namespace:uuid
    principal namespace:uuid
    metadata object
  • ]
Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-update-project-resource/index.html b/apis/shield-service-update-project-resource/index.html index 57d2ff3c2..5dc456954 100644 --- a/apis/shield-service-update-project-resource/index.html +++ b/apis/shield-service-update-project-resource/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Update resource​

Updates a resource in a project

Path Parameters
    projectId string required
    id string required
Request Body required
    name string required

    The name of the resource. Must be unique within the project.
    Example: my-resource

    title string

    The title can contain any UTF-8 character, used to provide a human-readable name for the resource. Can also be left empty.

    namespace string required

    The namespace of the resource. The resource namespace are created when permissions for that resource is created in Shield. If namespace doesn't exists the request will fail.
    Example: compute/instance

    principal format namespace:uuid or just uuid for user

    UserID or ServiceUserID that should be marked as owner of the resource. If not provided, the current logged in user will be made the resource owner.
    Example: user:92f69c3a-334b-4f25-90b8-4d4f3be6b825

    metadata object
Responses

A successful response.

Schema
    resource object
    id string
    name string

    Name of the resource. Must be unique within the project.

    createdAt date-time

    The time the resource was created.

    updatedAt date-time

    The time the resource was last updated.

    urn string
    projectId string
    namespace string
    principal string
    metadata object
Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-update-project/index.html b/apis/shield-service-update-project/index.html index 4c22711c3..13c1c7f8b 100644 --- a/apis/shield-service-update-project/index.html +++ b/apis/shield-service-update-project/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Update project​

Updates a project by ID

Path Parameters
    id string required
Request Body required
    name string required

    The name of the project. The name must be unique within the entire Shield instance. The name can contain only alphanumeric characters, dashes and underscores.
    Example: shield-playground

    title string

    The title can contain any UTF-8 character, used to provide a human-readable name for the project. Can also be left empty.
    Example: Shield Playground

    metadata object

    Metadata object for projects that can hold key value pairs defined in Project Metaschema.

    orgId string required

    unique id of the organization to which project belongs

Responses

A successful response.

Schema
    project object
    id string
    name string
    title string
    orgId string
    metadata object
    createdAt date-time

    The time the project was created.

    updatedAt date-time

    The time the project was last updated.

Loading...
- + \ No newline at end of file diff --git a/apis/shield-service-update-user/index.html b/apis/shield-service-update-user/index.html index 900190de8..376410138 100644 --- a/apis/shield-service-update-user/index.html +++ b/apis/shield-service-update-user/index.html @@ -7,13 +7,13 @@ - +
Skip to main content

Update user​

Update user

Path Parameters
    id string required
Request Body required
    name string

    The name of the user. The name must be unique within the entire Shield instance. The name can contain only alphanumeric characters, dashes and underscores and must start with a letter. If not provided, Shield automatically generates a name from the user email.

    email string required

    The email of the user. The email must be unique within the entire Shield instance.
    Example:"john.doe@raystack.org"

    metadata object

    Metadata object for users that can hold key value pairs pre-defined in User Metaschema. The metadata object can be used to store arbitrary information about the user such as label, description etc. By default the user metaschema contains labels and descriptions for the user. Update the same to add more fields to the user metadata object.
    Example:{"label": {"key1": "value1"}, "description": "User Description"}

    title string

    The title can contain any UTF-8 character, used to provide a human-readable name for the user. Can also be left empty.
    Example:"John Doe"

Responses

A successful response.

Schema
    user object
    id string
    name can either be empty or must start with a character

    Unique name of the user.

    title string

    Name of the user.

    email string
    metadata object
    createdAt date-time

    The time the user was created.

    updatedAt date-time

    The time the user was last updated.

    state string
Loading...
- + \ No newline at end of file diff --git a/assets/js/3b8c55ea.ca7079ed.js b/assets/js/3b8c55ea.0ab8fe16.js similarity index 58% rename from assets/js/3b8c55ea.ca7079ed.js rename to assets/js/3b8c55ea.0ab8fe16.js index 156b673a9..d3eff9ca7 100644 --- a/assets/js/3b8c55ea.ca7079ed.js +++ b/assets/js/3b8c55ea.0ab8fe16.js @@ -1 +1 @@ -"use strict";(self.webpackChunkshield=self.webpackChunkshield||[]).push([[3217],{89803:(e,a,t)=>{t.r(a),t.d(a,{assets:()=>o,contentTitle:()=>s,default:()=>u,frontMatter:()=>i,metadata:()=>r,toc:()=>d});var l=t(87462),n=(t(67294),t(3905));const i={},s="Installation",r={unversionedId:"installation",id:"installation",title:"Installation",description:"There are several approaches to install Shield.",source:"@site/docs/installation.md",sourceDirName:".",slug:"/installation",permalink:"/shield/installation",draft:!1,editUrl:"https://github.com/raystack/shield/edit/master/docs/docs/installation.md",tags:[],version:"current",frontMatter:{},sidebar:"docsSidebar",previous:{title:"Introduction",permalink:"/shield/"},next:{title:"Installation",permalink:"/shield/installation"}},o={},d=[{value:"Binary (Cross-platform)",id:"binary-cross-platform",level:3},{value:"macOS",id:"macos",level:4},{value:"Linux",id:"linux",level:4},{value:"Windows",id:"windows",level:4},{value:"Docker",id:"docker",level:3},{value:"Building from source",id:"building-from-source",level:3},{value:"As a native executable",id:"as-a-native-executable",level:4},{value:"As a Docker image",id:"as-a-docker-image",level:4},{value:"Verifying the installation\u200b",id:"verifying-the-installation",level:3},{value:"What's next",id:"whats-next",level:3}],p={toc:d};function u(e){let{components:a,...t}=e;return(0,n.kt)("wrapper",(0,l.Z)({},p,t,{components:a,mdxType:"MDXLayout"}),(0,n.kt)("h1",{id:"installation"},"Installation"),(0,n.kt)("p",null,"There are several approaches to install Shield."),(0,n.kt)("ol",null,(0,n.kt)("li",{parentName:"ol"},(0,n.kt)("a",{parentName:"li",href:"#binary-cross-platform"},"Using a pre-compiled binary")),(0,n.kt)("li",{parentName:"ol"},(0,n.kt)("a",{parentName:"li",href:"#docker"},"Using the Docker image")),(0,n.kt)("li",{parentName:"ol"},(0,n.kt)("a",{parentName:"li",href:"#building-from-source"},"Installing from source")),(0,n.kt)("li",{parentName:"ol"},(0,n.kt)("a",{parentName:"li",href:"https://github.com/raystack/charts/tree/main/stable/shield"},"Helm Charts"))),(0,n.kt)("h3",{id:"binary-cross-platform"},"Binary (Cross-platform)"),(0,n.kt)("p",null,"Download the appropriate version for your platform from ",(0,n.kt)("a",{parentName:"p",href:"https://github.com/raystack/shield/releases"},"releases")," page. Once downloaded, the binary can be run from anywhere.\nYou don\u2019t need to install it into a global location. This works well for shared hosts and other systems where you don\u2019t have a privileged account.\nIdeally, you should install it somewhere in your PATH for easy use. ",(0,n.kt)("inlineCode",{parentName:"p"},"/usr/local/bin")," is the most probable location."),(0,n.kt)("h4",{id:"macos"},"macOS"),(0,n.kt)("p",null,(0,n.kt)("inlineCode",{parentName:"p"},"Shield")," is available via a Homebrew Tap, and as downloadable binary from the ",(0,n.kt)("a",{parentName:"p",href:"https://github.com/raystack/shield/releases"},"releases")," page:"),(0,n.kt)("pre",null,(0,n.kt)("code",{parentName:"pre",className:"language-sh"},"$ brew install raystack/taps/shield\n")),(0,n.kt)("p",null,"To upgrade to the latest version:"),(0,n.kt)("pre",null,(0,n.kt)("code",{parentName:"pre",className:"language-sh"},"$ brew upgrade shield\n")),(0,n.kt)("h4",{id:"linux"},"Linux"),(0,n.kt)("p",null,(0,n.kt)("inlineCode",{parentName:"p"},"Shield")," is available as downloadable binaries from the ",(0,n.kt)("a",{parentName:"p",href:"https://github.com/raystack/shield/releases/latest"},"releases")," page. Download the ",(0,n.kt)("inlineCode",{parentName:"p"},".deb")," or ",(0,n.kt)("inlineCode",{parentName:"p"},".rpm")," from the releases page and install with ",(0,n.kt)("inlineCode",{parentName:"p"},"sudo dpkg -i")," and ",(0,n.kt)("inlineCode",{parentName:"p"},"sudo rpm -i")," respectively."),(0,n.kt)("h4",{id:"windows"},"Windows"),(0,n.kt)("p",null,(0,n.kt)("inlineCode",{parentName:"p"},"Shield")," is available via ",(0,n.kt)("a",{parentName:"p",href:"https://scoop.sh/"},"scoop"),", and as a downloadable binary from the ",(0,n.kt)("a",{parentName:"p",href:"https://github.com/raystack/shield/releases/latest"},"releases")," page:"),(0,n.kt)("pre",null,(0,n.kt)("code",{parentName:"pre",className:"language-sh"},"scoop bucket add shield https://github.com/raystack/scoop-bucket.git\n")),(0,n.kt)("p",null,"To upgrade to the latest version:"),(0,n.kt)("pre",null,(0,n.kt)("code",{parentName:"pre",className:"language-sh"},"scoop update shield\n")),(0,n.kt)("h3",{id:"docker"},"Docker"),(0,n.kt)("p",null,"We provide ready to use Docker container images. To pull the latest image: Make sure you have Spicedb and postgres running on your local and run the following."),(0,n.kt)("pre",null,(0,n.kt)("code",{parentName:"pre",className:"language-sh"},"$ docker pull raystack/shield\n")),(0,n.kt)("p",null,"To pull a specific version:"),(0,n.kt)("pre",null,(0,n.kt)("code",{parentName:"pre",className:"language-sh"},"$ docker pull raystack/shield:v0.5.1\n")),(0,n.kt)("p",null,"To run the docker image with minimum configurations:"),(0,n.kt)("pre",null,(0,n.kt)("code",{parentName:"pre",className:"language-sh"},"$ docker run -p 8080:8080 \\\n -e SHIELD_DB_DRIVER=postgres \\\n -e SHIELD_DB_URL=postgres://shield:@localhost:5432/shield?sslmode=disable \\\n -e SHIELD_SPICEDB_HOST=spicedb.localhost:50051 \\\n -e SHIELD_SPICEDB_PRE_SHARED_KEY=randomkey\n -v .config:.config\n raystack/shield server start\n")),(0,n.kt)("h3",{id:"building-from-source"},"Building from source"),(0,n.kt)("p",null,"Begin by cloning this repository then you have two ways in which you can build Shield:"),(0,n.kt)("ul",null,(0,n.kt)("li",{parentName:"ul"},"As a native executable"),(0,n.kt)("li",{parentName:"ul"},"As a docker image")),(0,n.kt)("p",null,"Run either of the following commands to clone and compile Shield from source"),(0,n.kt)("pre",null,(0,n.kt)("code",{parentName:"pre",className:"language-bash"},"$ git clone git@github.com:raystack/shield.git # (Using SSH Protocol)\n$ git clone https://github.com/raystack/shield.git # (Using HTTPS Protocol)\n")),(0,n.kt)("h4",{id:"as-a-native-executable"},"As a native executable"),(0,n.kt)("p",null,"To build shield as a native executable, run ",(0,n.kt)("inlineCode",{parentName:"p"},"make")," inside the cloned repository."),(0,n.kt)("pre",null,(0,n.kt)("code",{parentName:"pre",className:"language-bash"},"$ make\n")),(0,n.kt)("p",null,"This will create the ",(0,n.kt)("strong",{parentName:"p"},(0,n.kt)("inlineCode",{parentName:"strong"},"shield"))," binary in the root directory. Initialise server and client config file. Customise the ",(0,n.kt)("inlineCode",{parentName:"p"},"config.yaml")," file with your local configurations."),(0,n.kt)("pre",null,(0,n.kt)("code",{parentName:"pre",className:"language-bash"},"$ ./shield config init\n")),(0,n.kt)("p",null,"Run database migrations"),(0,n.kt)("pre",null,(0,n.kt)("code",{parentName:"pre",className:"language-bash"},"$ ./shield server migrate\n")),(0,n.kt)("p",null,"Start Shield server"),(0,n.kt)("pre",null,(0,n.kt)("code",{parentName:"pre",className:"language-bash"},"$ ./shield server start\n")),(0,n.kt)("h4",{id:"as-a-docker-image"},"As a Docker image"),(0,n.kt)("p",null,"Building Shield's Docker image is just a simple, just run docker build command and optionally name the image"),(0,n.kt)("pre",null,(0,n.kt)("code",{parentName:"pre",className:"language-bash"},"$ docker build . -t shield\n")),(0,n.kt)("h3",{id:"verifying-the-installation"},"Verifying the installation\u200b"),(0,n.kt)("p",null,"To verify if Shield is properly installed, run ",(0,n.kt)("inlineCode",{parentName:"p"},"shield --help")," on your system. You should see help output. If you are executing it from the command line, make sure it is on your PATH or you may get an error about Shield not being found."),(0,n.kt)("pre",null,(0,n.kt)("code",{parentName:"pre",className:"language-bash"},"$ ./shield --help\n")),(0,n.kt)("h3",{id:"whats-next"},"What's next"),(0,n.kt)("ul",null,(0,n.kt)("li",{parentName:"ul"},"See the ",(0,n.kt)("a",{parentName:"li",href:"/shield/configurations"},"Configurations")," page on how to setup Shield server and client"),(0,n.kt)("li",{parentName:"ul"},"See the ",(0,n.kt)("a",{parentName:"li",href:"/shield/reference/cli"},"CLI Reference")," for a complete list of commands and options.")))}u.isMDXComponent=!0}}]); \ No newline at end of file +"use strict";(self.webpackChunkshield=self.webpackChunkshield||[]).push([[3217],{89803:(e,a,t)=>{t.r(a),t.d(a,{assets:()=>o,contentTitle:()=>s,default:()=>u,frontMatter:()=>i,metadata:()=>r,toc:()=>d});var l=t(87462),n=(t(67294),t(3905));const i={},s="Installation",r={unversionedId:"installation",id:"installation",title:"Installation",description:"There are several approaches to install Shield.",source:"@site/docs/installation.md",sourceDirName:".",slug:"/installation",permalink:"/shield/installation",draft:!1,editUrl:"https://github.com/raystack/shield/edit/master/docs/docs/installation.md",tags:[],version:"current",frontMatter:{},sidebar:"docsSidebar",previous:{title:"Introduction",permalink:"/shield/"},next:{title:"Installation",permalink:"/shield/installation"}},o={},d=[{value:"Binary (Cross-platform)",id:"binary-cross-platform",level:3},{value:"macOS",id:"macos",level:4},{value:"Linux",id:"linux",level:4},{value:"Windows",id:"windows",level:4},{value:"Docker",id:"docker",level:3},{value:"Building from source",id:"building-from-source",level:3},{value:"As a native executable",id:"as-a-native-executable",level:4},{value:"As a Docker image",id:"as-a-docker-image",level:4},{value:"Verifying the installation\u200b",id:"verifying-the-installation",level:3},{value:"What's next",id:"whats-next",level:3}],p={toc:d};function u(e){let{components:a,...t}=e;return(0,n.kt)("wrapper",(0,l.Z)({},p,t,{components:a,mdxType:"MDXLayout"}),(0,n.kt)("h1",{id:"installation"},"Installation"),(0,n.kt)("p",null,"There are several approaches to install Shield."),(0,n.kt)("ol",null,(0,n.kt)("li",{parentName:"ol"},(0,n.kt)("a",{parentName:"li",href:"#binary-cross-platform"},"Using a pre-compiled binary")),(0,n.kt)("li",{parentName:"ol"},(0,n.kt)("a",{parentName:"li",href:"#docker"},"Using the Docker image")),(0,n.kt)("li",{parentName:"ol"},(0,n.kt)("a",{parentName:"li",href:"#building-from-source"},"Installing from source")),(0,n.kt)("li",{parentName:"ol"},(0,n.kt)("a",{parentName:"li",href:"https://github.com/raystack/charts/tree/main/stable/shield"},"Helm Charts"))),(0,n.kt)("h3",{id:"binary-cross-platform"},"Binary (Cross-platform)"),(0,n.kt)("p",null,"Download the appropriate version for your platform from ",(0,n.kt)("a",{parentName:"p",href:"https://github.com/raystack/shield/releases"},"releases")," page. Once downloaded, the binary can be run from anywhere.\nYou don\u2019t need to install it into a global location. This works well for shared hosts and other systems where you don\u2019t have a privileged account.\nIdeally, you should install it somewhere in your PATH for easy use. ",(0,n.kt)("inlineCode",{parentName:"p"},"/usr/local/bin")," is the most probable location."),(0,n.kt)("h4",{id:"macos"},"macOS"),(0,n.kt)("p",null,(0,n.kt)("inlineCode",{parentName:"p"},"Shield")," is available via a Homebrew Tap, and as downloadable binary from the ",(0,n.kt)("a",{parentName:"p",href:"https://github.com/raystack/shield/releases"},"releases")," page:"),(0,n.kt)("pre",null,(0,n.kt)("code",{parentName:"pre",className:"language-sh"},"$ brew install raystack/taps/shield\n")),(0,n.kt)("p",null,"To upgrade to the latest version:"),(0,n.kt)("pre",null,(0,n.kt)("code",{parentName:"pre",className:"language-sh"},"$ brew upgrade shield\n")),(0,n.kt)("h4",{id:"linux"},"Linux"),(0,n.kt)("p",null,(0,n.kt)("inlineCode",{parentName:"p"},"Shield")," is available as downloadable binaries from the ",(0,n.kt)("a",{parentName:"p",href:"https://github.com/raystack/shield/releases/latest"},"releases")," page. Download the ",(0,n.kt)("inlineCode",{parentName:"p"},".deb")," or ",(0,n.kt)("inlineCode",{parentName:"p"},".rpm")," from the releases page and install with ",(0,n.kt)("inlineCode",{parentName:"p"},"sudo dpkg -i")," and ",(0,n.kt)("inlineCode",{parentName:"p"},"sudo rpm -i")," respectively."),(0,n.kt)("h4",{id:"windows"},"Windows"),(0,n.kt)("p",null,(0,n.kt)("inlineCode",{parentName:"p"},"Shield")," is available via ",(0,n.kt)("a",{parentName:"p",href:"https://scoop.sh/"},"scoop"),", and as a downloadable binary from the ",(0,n.kt)("a",{parentName:"p",href:"https://github.com/raystack/shield/releases/latest"},"releases")," page:"),(0,n.kt)("pre",null,(0,n.kt)("code",{parentName:"pre",className:"language-sh"},"scoop bucket add shield https://github.com/raystack/scoop-bucket.git\n")),(0,n.kt)("p",null,"To upgrade to the latest version:"),(0,n.kt)("pre",null,(0,n.kt)("code",{parentName:"pre",className:"language-sh"},"scoop update shield\n")),(0,n.kt)("h3",{id:"docker"},"Docker"),(0,n.kt)("p",null,"We provide ready to use Docker container images. To pull the latest image: Make sure you have Spicedb and postgres running on your local and run the following."),(0,n.kt)("pre",null,(0,n.kt)("code",{parentName:"pre",className:"language-sh"},"$ docker pull raystack/shield\n")),(0,n.kt)("p",null,"To pull a specific version:"),(0,n.kt)("pre",null,(0,n.kt)("code",{parentName:"pre",className:"language-sh"},"$ docker pull raystack/shield:v0.6.2-arm64\n")),(0,n.kt)("p",null,"To run the docker image with minimum configurations:"),(0,n.kt)("pre",null,(0,n.kt)("code",{parentName:"pre",className:"language-sh"},"$ docker run -p 8080:8080 \\\n -e SHIELD_DB_DRIVER=postgres \\\n -e SHIELD_DB_URL=postgres://shield:@localhost:5432/shield?sslmode=disable \\\n -e SHIELD_SPICEDB_HOST=spicedb.localhost:50051 \\\n -e SHIELD_SPICEDB_PRE_SHARED_KEY=randomkey\n -v .config:.config\n raystack/shield server start\n")),(0,n.kt)("h3",{id:"building-from-source"},"Building from source"),(0,n.kt)("p",null,"Begin by cloning this repository then you have two ways in which you can build Shield:"),(0,n.kt)("ul",null,(0,n.kt)("li",{parentName:"ul"},"As a native executable"),(0,n.kt)("li",{parentName:"ul"},"As a docker image")),(0,n.kt)("p",null,"Run either of the following commands to clone and compile Shield from source"),(0,n.kt)("pre",null,(0,n.kt)("code",{parentName:"pre",className:"language-bash"},"$ git clone git@github.com:raystack/shield.git # (Using SSH Protocol)\n$ git clone https://github.com/raystack/shield.git # (Using HTTPS Protocol)\n")),(0,n.kt)("h4",{id:"as-a-native-executable"},"As a native executable"),(0,n.kt)("p",null,"To build shield as a native executable, run ",(0,n.kt)("inlineCode",{parentName:"p"},"make")," inside the cloned repository."),(0,n.kt)("pre",null,(0,n.kt)("code",{parentName:"pre",className:"language-bash"},"$ make\n")),(0,n.kt)("p",null,"This will create the ",(0,n.kt)("strong",{parentName:"p"},(0,n.kt)("inlineCode",{parentName:"strong"},"shield"))," binary in the root directory. Initialise server and client config file. Customise the ",(0,n.kt)("inlineCode",{parentName:"p"},"config.yaml")," file with your local configurations."),(0,n.kt)("pre",null,(0,n.kt)("code",{parentName:"pre",className:"language-bash"},"$ ./shield config init\n")),(0,n.kt)("p",null,"Run database migrations"),(0,n.kt)("pre",null,(0,n.kt)("code",{parentName:"pre",className:"language-bash"},"$ ./shield server migrate\n")),(0,n.kt)("p",null,"Start Shield server"),(0,n.kt)("pre",null,(0,n.kt)("code",{parentName:"pre",className:"language-bash"},"$ ./shield server start\n")),(0,n.kt)("h4",{id:"as-a-docker-image"},"As a Docker image"),(0,n.kt)("p",null,"Building Shield's Docker image is just a simple, just run docker build command and optionally name the image"),(0,n.kt)("pre",null,(0,n.kt)("code",{parentName:"pre",className:"language-bash"},"$ docker build . -t shield\n")),(0,n.kt)("h3",{id:"verifying-the-installation"},"Verifying the installation\u200b"),(0,n.kt)("p",null,"To verify if Shield is properly installed, run ",(0,n.kt)("inlineCode",{parentName:"p"},"shield --help")," on your system. You should see help output. If you are executing it from the command line, make sure it is on your PATH or you may get an error about Shield not being found."),(0,n.kt)("pre",null,(0,n.kt)("code",{parentName:"pre",className:"language-bash"},"$ ./shield --help\n")),(0,n.kt)("h3",{id:"whats-next"},"What's next"),(0,n.kt)("ul",null,(0,n.kt)("li",{parentName:"ul"},"See the ",(0,n.kt)("a",{parentName:"li",href:"/shield/configurations"},"Configurations")," page on how to setup Shield server and client"),(0,n.kt)("li",{parentName:"ul"},"See the ",(0,n.kt)("a",{parentName:"li",href:"/shield/reference/cli"},"CLI Reference")," for a complete list of commands and options.")))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/a09c2993.1ff92efc.js b/assets/js/a09c2993.1ff92efc.js new file mode 100644 index 000000000..1d33ef916 --- /dev/null +++ b/assets/js/a09c2993.1ff92efc.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkshield=self.webpackChunkshield||[]).push([[4128],{88495:(e,t,i)=>{i.r(t),i.d(t,{assets:()=>l,contentTitle:()=>s,default:()=>c,frontMatter:()=>a,metadata:()=>r,toc:()=>d});var n=i(87462),o=(i(67294),i(3905));const a={id:"introduction",slug:"/"},s="Introduction",r={unversionedId:"introduction",id:"introduction",title:"Introduction",description:"Welcome to the introductory guide to Shield! We cover what Shield is, what problems it can solve, how it works, and how you can get started using it. If you are familiar with the basics of Shield, the guides provides a more detailed reference of available features.",source:"@site/docs/introduction.md",sourceDirName:".",slug:"/",permalink:"/shield/",draft:!1,editUrl:"https://github.com/raystack/shield/edit/master/docs/docs/introduction.md",tags:[],version:"current",frontMatter:{id:"introduction",slug:"/"},sidebar:"docsSidebar",next:{title:"Installation",permalink:"/shield/installation"}},l={},d=[{value:"What is Shield?",id:"what-is-shield",level:2},{value:"How does shield work?",id:"how-does-shield-work",level:2},{value:"Key Features",id:"key-features",level:2},{value:"Using Shield",id:"using-shield",level:2},{value:"Shield Command Line Interface",id:"shield-command-line-interface",level:3},{value:"HTTPS API",id:"https-api",level:3},{value:"Admin Portal",id:"admin-portal",level:3},{value:"Where to go from here",id:"where-to-go-from-here",level:2}],h={toc:d};function c(e){let{components:t,...a}=e;return(0,o.kt)("wrapper",(0,n.Z)({},h,a,{components:t,mdxType:"MDXLayout"}),(0,o.kt)("h1",{id:"introduction"},"Introduction"),(0,o.kt)("p",null,"Welcome to the introductory guide to Shield! We cover what Shield is, what problems it can solve, how it works, and how you can get started using it. If you are familiar with the basics of Shield, the guides provides a more detailed reference of available features."),(0,o.kt)("h2",{id:"what-is-shield"},"What is Shield?"),(0,o.kt)("p",null,"Shield by Raystack is a role-based cloud-native user management system and authorization server for your applications and API endpoints. It is API-driven and provides CLI, HTTP/GRPC APIs and an Admin Portal. Shield is designed to be easy to use Identity and Access Management tool which handles user authentication by providing a Single-Sign-On(SSO) with any provider which adheres to the OIDC Protocol. It checks the client's credentials and permissions against the defined access policies before allowing or denying access to the backend services."),(0,o.kt)("p",null,(0,o.kt)("img",{alt:"Shield flow diagram",src:i(46144).Z,width:"3199",height:"2176"})),(0,o.kt)("h2",{id:"how-does-shield-work"},"How does shield work?"),(0,o.kt)("p",null,"Here are the steps to work with Shield."),(0,o.kt)("ol",null,(0,o.kt)("li",{parentName:"ol"},"Configure shield: Shield has various tuning parameters that can be configured to suit the needs of the organization.\nThis includes the configuration of the database, OIDC provider, email provider, etc."),(0,o.kt)("li",{parentName:"ol"},"Configure policies: This step involves definition of resource types that will exist in the connected backend.\nA resource is a protected backend service for example an order management service or user picture library. User can\nalso configure the roles and permissions to be assigned to the users."),(0,o.kt)("li",{parentName:"ol"},"Connecting frontend: Shield provides a set of APIs that can be used by the frontend to authenticate, authorize and\nmanage users. The frontend can be a web application, mobile application or any other application that can make HTTP\nrequests.")),(0,o.kt)("h2",{id:"key-features"},"Key Features"),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("p",{parentName:"li"},(0,o.kt)("strong",{parentName:"p"},"Single-Sign-On(SSO)"),": Shield implements the OpenID Connect(OIDC) Protocol that extends the OAuth 2.0 framework to provide authentication and identity information, allowing users to authenticate once and access multiple applications seamlessly. It also enables applications to obtain user identity information for authorization purposes. A Single login and logout for all the underlying application and resources ensure a seamless user experience.")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("p",{parentName:"li"},(0,o.kt)("strong",{parentName:"p"},"Multiple sources of user identities"),": Shield allows seamless integration with any identity provider that supports OIDC, enabling a wide range of options for user authentication. This flexibility empowers organizations to leverage their preferred identity providers, such as Google, Microsoft Azure AD, Github, LinkedIn or others, to authenticate and manage user identities within their organisation's ecosystem.")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("p",{parentName:"li"},(0,o.kt)("strong",{parentName:"p"},"Role-Based-Access-Control(RBAC)"),": Shield follows the RBAC model, which means you can assign roles to users, groups, or service accounts. This simplifies access management by providing predefined roles with specific permissions, reducing the need for manual permission assignments.")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("p",{parentName:"li"},(0,o.kt)("strong",{parentName:"p"},"Resource Management"),": Shield provides API to create and manage organizations/projects. Admins can create projects and groups within organizations. In addition, group admins can manage groups, add-remove members to the groups, and assign roles to these principals. Using Shield, admins can define policies which bind roles to the underlying resources."))),(0,o.kt)("h2",{id:"using-shield"},"Using Shield"),(0,o.kt)("p",null,"You can manage organizations, projects, group, users and resources in any of the following ways:"),(0,o.kt)("h3",{id:"shield-command-line-interface"},"Shield Command Line Interface"),(0,o.kt)("p",null,"You can use the Shield command line interface to issue commands and to perform the entire Shield features. Using the command line can be faster and more convenient than using API. For more information on using the Shield CLI, see the CLI Reference page."),(0,o.kt)("h3",{id:"https-api"},"HTTPS API"),(0,o.kt)("p",null,"You can manage relation creation, checking authorization on a resource and much more by using the Shield HTTPS API, which lets you issue HTTPS requests directly to the service. For more information, see the API Reference page."),(0,o.kt)("h3",{id:"admin-portal"},"Admin Portal"),(0,o.kt)("p",null,"Besides HTTP APIs and CLI tool, Shield provides an out-of-the-box UI for admins to configure SSO for the clients and manage roles, users, groups and organisations in one place."),(0,o.kt)("h2",{id:"where-to-go-from-here"},"Where to go from here"),(0,o.kt)("p",null,"See the ",(0,o.kt)("a",{parentName:"p",href:"./installation"},"installation")," page to install the Shield CLI. Next, we recommend completing the guides. The tour provides an overview of most of the existing functionality of Shield and takes approximately 30 minutes to complete."),(0,o.kt)("p",null,"After completing the tour, check out the remainder of the documentation in the reference and concepts sections for your specific areas of interest. We've aimed to provide as much documentation as we can for the various components of Shield to give you a full understanding of Shield's surface area."),(0,o.kt)("p",null,"Finally, follow the project on ",(0,o.kt)("a",{parentName:"p",href:"https://github.com/raystack/shield"},"GitHub"),", and contact us if you'd like to get involved."))}c.isMDXComponent=!0},46144:(e,t,i)=>{i.d(t,{Z:()=>n});const n=i.p+"assets/images/shield-flow-diagram-2edac8775d2fcc34392ab56f8e0080ce.png"}}]); \ No newline at end of file diff --git a/assets/js/a09c2993.8d3dc7a7.js b/assets/js/a09c2993.8d3dc7a7.js deleted file mode 100644 index a3b9497ef..000000000 --- a/assets/js/a09c2993.8d3dc7a7.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkshield=self.webpackChunkshield||[]).push([[4128],{88495:(e,t,i)=>{i.r(t),i.d(t,{assets:()=>l,contentTitle:()=>s,default:()=>c,frontMatter:()=>a,metadata:()=>r,toc:()=>d});var n=i(87462),o=(i(67294),i(3905));const a={id:"introduction",slug:"/"},s="Introduction",r={unversionedId:"introduction",id:"introduction",title:"Introduction",description:"Welcome to the introductory guide to Shield! We cover what Shield is, what problems it can solve, how it works, and how you can get started using it. If you are familiar with the basics of Shield, the guides provides a more detailed reference of available features.",source:"@site/docs/introduction.md",sourceDirName:".",slug:"/",permalink:"/shield/",draft:!1,editUrl:"https://github.com/raystack/shield/edit/master/docs/docs/introduction.md",tags:[],version:"current",frontMatter:{id:"introduction",slug:"/"},sidebar:"docsSidebar",next:{title:"Installation",permalink:"/shield/installation"}},l={},d=[{value:"What is Shield?",id:"what-is-shield",level:2},{value:"How does shield work?",id:"how-does-shield-work",level:2},{value:"Key Features",id:"key-features",level:2},{value:"Using Shield",id:"using-shield",level:2},{value:"Shield Command Line Interface",id:"shield-command-line-interface",level:3},{value:"HTTPS API",id:"https-api",level:3},{value:"Admin Portal",id:"admin-portal",level:3},{value:"Where to go from here",id:"where-to-go-from-here",level:2}],h={toc:d};function c(e){let{components:t,...a}=e;return(0,o.kt)("wrapper",(0,n.Z)({},h,a,{components:t,mdxType:"MDXLayout"}),(0,o.kt)("h1",{id:"introduction"},"Introduction"),(0,o.kt)("p",null,"Welcome to the introductory guide to Shield! We cover what Shield is, what problems it can solve, how it works, and how you can get started using it. If you are familiar with the basics of Shield, the guides provides a more detailed reference of available features."),(0,o.kt)("h2",{id:"what-is-shield"},"What is Shield?"),(0,o.kt)("p",null,"Shield by Raystack is a role-based cloud-native user management system and authorization server for your applications and API endpoints. It is API-driven and provides CLI, HTTP/GRPC APIs and an Admin Portal. Shield is designed to be easy to use Identity and Access Management tool which handles user authentication by providing a Single-Sign-On(SSO) with any provider which adheres to the OIDC Protocol. It checks the client's credentials and permissions against the defined access policies before allowing or denying access to the backend services."),(0,o.kt)("p",null,(0,o.kt)("img",{alt:"Shield flow diagram",src:i(46144).Z,width:"3199",height:"2176"})),(0,o.kt)("h2",{id:"how-does-shield-work"},"How does shield work?"),(0,o.kt)("p",null,"Here are the steps to work with Shield."),(0,o.kt)("ol",null,(0,o.kt)("li",{parentName:"ol"},(0,o.kt)("p",{parentName:"li"},"Configure policies: This step involves definition of resource types that will exist in the connected backend. User can also configure the roles and permissions that exist.")),(0,o.kt)("li",{parentName:"ol"},(0,o.kt)("p",{parentName:"li"},"Configure rules: This step involves defining the authorization(via authz middleware) and resource creation(via hook) for each path in the backend.")),(0,o.kt)("li",{parentName:"ol"},(0,o.kt)("p",{parentName:"li"},"Making Shield proxy request: User can now hit at the shield server followed by the url path."))),(0,o.kt)("h2",{id:"key-features"},"Key Features"),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("p",{parentName:"li"},(0,o.kt)("strong",{parentName:"p"},"Single-Sign-On(SSO)"),": Shield implements the OpenID Connect(OIDC) Protocol that extends the OAuth 2.0 framework to provide authentication and identity information, allowing users to authenticate once and access multiple applications seamlessly. It also enables applications to obtain user identity information for authorization purposes. A Single login and logout for all the underlying application and resources ensure a seamless user experience.")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("p",{parentName:"li"},(0,o.kt)("strong",{parentName:"p"},"Multiple sources of user identities"),": Shield allows seamless integration with any identity provider that supports OIDC, enabling a wide range of options for user authentication. This flexibility empowers organizations to leverage their preferred identity providers, such as Google, Microsoft Azure AD, Github, LinkedIn or others, to authenticate and manage user identities within their organisation's ecosystem.")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("p",{parentName:"li"},(0,o.kt)("strong",{parentName:"p"},"Role-Based-Access-Control(RBAC)"),": Shield follows the RBAC model, which means you can assign roles to users, groups, or service accounts. This simplifies access management by providing predefined roles with specific permissions, reducing the need for manual permission assignments.")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("p",{parentName:"li"},(0,o.kt)("strong",{parentName:"p"},"Resource Management"),": Shield provides API to create and manage organizations/projects. Admins can create projects and groups within organizations. In addition, group admins can manage groups, add-remove members to the groups, and assign roles to these principals. Using Shield, admins can define policies which bind roles to the underlying resources."))),(0,o.kt)("h2",{id:"using-shield"},"Using Shield"),(0,o.kt)("p",null,"You can manage organizations, projects, group, users and resources in any of the following ways:"),(0,o.kt)("h3",{id:"shield-command-line-interface"},"Shield Command Line Interface"),(0,o.kt)("p",null,"You can use the Shield command line interface to issue commands and to perform the entire Shield features. Using the command line can be faster and more convenient than using API. For more information on using the Shield CLI, see the CLI Reference page."),(0,o.kt)("h3",{id:"https-api"},"HTTPS API"),(0,o.kt)("p",null,"You can manage relation creation, checking authorization on a resource and much more by using the Shield HTTPS API, which lets you issue HTTPS requests directly to the service. For more information, see the API Reference page."),(0,o.kt)("h3",{id:"admin-portal"},"Admin Portal"),(0,o.kt)("p",null,"Besides HTTP APIs and CLI tool, Shield provides an provides an out-of-the-box UI for admins to configure SSO for the clients and manage roles, users, groups and organisations in one place."),(0,o.kt)("h2",{id:"where-to-go-from-here"},"Where to go from here"),(0,o.kt)("p",null,"See the ",(0,o.kt)("a",{parentName:"p",href:"./installation"},"installation")," page to install the Shield CLI. Next, we recommend completing the guides. The tour provides an overview of most of the existing functionality of Shield and takes approximately 30 minutes to complete."),(0,o.kt)("p",null,"After completing the tour, check out the remainder of the documentation in the reference and concepts sections for your specific areas of interest. We've aimed to provide as much documentation as we can for the various components of Shield to give you a full understanding of Shield's surface area."),(0,o.kt)("p",null,"Finally, follow the project on ",(0,o.kt)("a",{parentName:"p",href:"https://github.com/raystack/shield"},"GitHub"),", and contact us if you'd like to get involved."))}c.isMDXComponent=!0},46144:(e,t,i)=>{i.d(t,{Z:()=>n});const n=i.p+"assets/images/shield-flow-diagram-2edac8775d2fcc34392ab56f8e0080ce.png"}}]); \ No newline at end of file diff --git a/assets/js/runtime~main.0bbcbf1c.js b/assets/js/runtime~main.e6ffe0a2.js similarity index 98% rename from assets/js/runtime~main.0bbcbf1c.js rename to assets/js/runtime~main.e6ffe0a2.js index efe25abc8..3ca62a792 100644 --- a/assets/js/runtime~main.0bbcbf1c.js +++ b/assets/js/runtime~main.e6ffe0a2.js @@ -1 +1 @@ -(()=>{"use strict";var e,a,f,c,d,b={},t={};function r(e){var a=t[e];if(void 0!==a)return a.exports;var f=t[e]={id:e,loaded:!1,exports:{}};return b[e].call(f.exports,f,f.exports,r),f.loaded=!0,f.exports}r.m=b,r.c=t,e=[],r.O=(a,f,c,d)=>{if(!f){var b=1/0;for(i=0;i=d)&&Object.keys(r.O).every((e=>r.O[e](f[o])))?f.splice(o--,1):(t=!1,d0&&e[i-1][2]>d;i--)e[i]=e[i-1];e[i]=[f,c,d]},r.n=e=>{var a=e&&e.__esModule?()=>e.default:()=>e;return r.d(a,{a:a}),a},f=Object.getPrototypeOf?e=>Object.getPrototypeOf(e):e=>e.__proto__,r.t=function(e,c){if(1&c&&(e=this(e)),8&c)return e;if("object"==typeof e&&e){if(4&c&&e.__esModule)return e;if(16&c&&"function"==typeof e.then)return e}var d=Object.create(null);r.r(d);var b={};a=a||[null,f({}),f([]),f(f)];for(var t=2&c&&e;"object"==typeof t&&!~a.indexOf(t);t=f(t))Object.getOwnPropertyNames(t).forEach((a=>b[a]=()=>e[a]));return b.default=()=>e,r.d(d,b),d},r.d=(e,a)=>{for(var f in a)r.o(a,f)&&!r.o(e,f)&&Object.defineProperty(e,f,{enumerable:!0,get:a[f]})},r.f={},r.e=e=>Promise.all(Object.keys(r.f).reduce(((a,f)=>(r.f[f](e,a),a)),[])),r.u=e=>"assets/js/"+({0:"81799e41",53:"935f2afb",154:"063bcf8c",258:"639c8683",521:"79755079",559:"757440e1",591:"56114c18",608:"af650176",613:"154c7c82",627:"b379a172",629:"0b1a0c1d",747:"9450a92f",807:"15bd7140",849:"5e4290c3",960:"91c76d4c",1001:"a0223cec",1026:"af591bac",1045:"525e7e1c",1087:"d8dadad9",1129:"235e47fd",1157:"8b16dfca",1204:"4ebe2796",1303:"bd051426",1319:"678c4125",1345:"f78cb8d5",1352:"137afead",1379:"7cee132a",1466:"36ff4aed",1553:"122a9a0a",1575:"8444b4ba",1621:"be08f2d0",1630:"3d97ff3e",1645:"b8265ab6",1692:"939208dc",1740:"dc59a77e",1893:"4c5e977b",1960:"07fa978f",1993:"acb3a279",1998:"da2b3fe7",2001:"732169bb",2085:"ba704184",2141:"589c6686",2223:"4c441f1e",2257:"2ec705b5",2297:"1e399fa0",2352:"f16281c3",2381:"2c0852f3",2423:"1f82dfc4",2486:"0741da40",2546:"8a1d978c",2557:"7e44693c",2568:"2416e5e0",2611:"c44fb328",2653:"0b2e5fa6",2734:"addd01e7",2750:"4217aa77",2753:"3ec3f58c",2782:"6cb47c0a",2819:"7614d37a",2828:"eab61343",2849:"6e55269d",2854:"14f70d12",2861:"0a6489c4",3017:"8656d2cb",3030:"6758bc63",3045:"973f92f3",3068:"b1592759",3081:"41993d15",3138:"c1540892",3191:"57782163",3217:"3b8c55ea",3226:"a0b50537",3351:"d6375c27",3523:"a5d17473",3626:"0862b264",3651:"f1fe12d1",3715:"39c35be1",3911:"69babfcc",3942:"fb2e4ac3",4026:"e6721467",4070:"f35f9779",4128:"a09c2993",4155:"974e60fa",4163:"c592e353",4194:"2b747206",4258:"6bd67bec",4409:"58175526",4504:"79c1ef57",4554:"329028fe",4610:"90c78a7a",4656:"b314e256",4727:"38240a34",4777:"30dbb125",4887:"2a52c330",5274:"e7b14a6e",5346:"85ab9c8d",5442:"e106a72b",5464:"00e4296b",5468:"4dae9392",5481:"619ee569",5640:"b12cc002",5660:"05f89af9",5696:"15b0aad8",5771:"e9c6cd3d",5873:"9815d18f",5879:"c3547753",6045:"fdfd3bf4",6122:"b8257e6e",6179:"6a90f76b",6217:"d9e16301",6389:"0cbcb03e",6430:"8778ff6c",6453:"7c2fa695",6458:"0c9bd6d0",6622:"c91fffbe",6698:"0563b9c0",6726:"3e624669",6786:"83a85fa4",6832:"8e46894b",6886:"8a1416ba",6910:"5d7f3e2f",6997:"1a8b86dc",7082:"442db9bd",7377:"99b2a733",7381:"9470cc54",7451:"48d4592f",7745:"430ce505",7825:"c13e6886",7858:"7e62c215",7888:"971d47e0",7919:"c389f5a0",7952:"6550eba9",7966:"eb0f1f62",7977:"04e56296",7995:"fbdf8469",8022:"4fdd65ff",8024:"b064323e",8042:"89a0316a",8066:"e953480e",8075:"24e631b4",8195:"d46c5637",8274:"0d47d022",8312:"57028ef1",8318:"3041af2a",8336:"44e33a92",8346:"3bb2fad9",8456:"2c5a41d0",8474:"38f3e015",8592:"common",8642:"bfecf59d",8726:"06fd825a",8859:"16a04d33",9008:"628e1422",9117:"96fc3af1",9118:"f0c85612",9377:"399652c8",9390:"eb0d9f45",9492:"351af5fd",9514:"1be78505",9764:"0ab57e89",9793:"749f4d75",9806:"09671944",9810:"5ee7b1bc",9813:"c92f0bff",9817:"14eb3368",9827:"3f27c6d7",9830:"b9c7d324",9960:"93da10dc",9961:"84ea66e6",9973:"f019fae4"}[e]||e)+"."+{0:"12cab899",53:"dd066653",70:"ec51fc24",121:"e732c399",154:"3826a6c6",258:"fbb5caf7",422:"c69e3681",521:"d9bec8ea",559:"ecff7f7e",591:"b3178ba1",608:"77f1efb6",613:"7a2396e9",627:"df14c143",629:"0bdaa4b1",747:"af9a6643",786:"0c11d2d9",807:"206aaaa0",823:"5d108ea5",849:"572e7599",932:"f6294c44",960:"fdb16066",967:"7b6d7bad",1001:"288c56c0",1011:"3a633f25",1026:"2e14197e",1045:"bd72fda4",1059:"d60c2959",1087:"f266084a",1129:"4b7ba4aa",1157:"bf1933ae",1204:"37454474",1274:"f3d2efd1",1303:"671f62e5",1319:"d4630018",1345:"3cf61c6d",1352:"110c30a3",1379:"0198cf22",1443:"8d5c8789",1466:"c776323c",1553:"33e5ea0d",1575:"fdb47103",1621:"6824b191",1630:"c7f28ca1",1645:"05fde32d",1692:"4d2e97a4",1736:"a494fbad",1740:"0583ac5f",1893:"0a97cea0",1960:"b2f09096",1993:"40dddba2",1998:"eeb52806",2001:"fe58cd7f",2085:"12c9adf9",2141:"ca836d24",2223:"63784b94",2257:"889d87ac",2297:"737fbd20",2352:"fb3a8d5c",2381:"92c4e725",2423:"79ad26b5",2444:"13a1a6c7",2486:"cb2a8f22",2494:"d188545c",2546:"e808a143",2557:"42acab2c",2568:"d7a8af24",2611:"22b294be",2653:"f58b590f",2734:"199cbf65",2750:"42d4bc78",2753:"80b49527",2782:"b04c48df",2819:"9a48f786",2828:"3c5a2429",2849:"3998f505",2854:"727c5525",2861:"88357189",3017:"87371d87",3030:"d3360b03",3045:"ba3373a2",3068:"85911bf0",3081:"0d1a6fb5",3138:"08134960",3180:"ef651182",3191:"764b3cb9",3217:"ca7079ed",3226:"82ced913",3351:"ab03702e",3523:"6e0ef9e3",3540:"538ab423",3594:"831167a1",3626:"4aed4c75",3651:"50b2d57e",3715:"6b7e4d6f",3871:"38eb1fd5",3911:"ff874f76",3942:"21521e27",4026:"efc41b51",4070:"7f84e230",4128:"8d3dc7a7",4155:"73d3454d",4163:"9ec7d9a7",4194:"84c6ffbc",4258:"6f893550",4409:"6976d163",4504:"e81263c8",4554:"12b77b13",4604:"96dadf49",4610:"6fa61fa7",4656:"ded2d0ba",4727:"816c463c",4777:"36127841",4887:"442c5835",4972:"a5eddc14",5274:"dd7329dd",5346:"700bf39d",5397:"7b3da98e",5442:"3d13e5aa",5464:"617c5446",5468:"57add63c",5481:"2fbdceaf",5640:"02a7e01a",5660:"ef1f9327",5696:"cc8c528a",5771:"284c2a47",5815:"79e381cd",5873:"feb8ed3b",5879:"ee888fcd",5883:"efbd6263",6045:"d2bd838a",6122:"8cdada41",6179:"3db7d7b7",6217:"851ad904",6305:"7720ae64",6389:"f5a5cebb",6430:"9691ae7d",6453:"3f019964",6458:"fd882918",6622:"7c731dc9",6698:"68e11e46",6726:"90e21389",6786:"9ee3c3c9",6788:"ec751b73",6832:"3e953144",6886:"d87882dd",6910:"38de56a0",6942:"5de8f085",6997:"d45a282e",7064:"ff4bf31c",7082:"31dc04ea",7377:"5054ae83",7381:"e09aef96",7451:"a388e253",7745:"78b814b9",7825:"24eeaa4e",7858:"1d01e735",7888:"bf815af6",7919:"1c6862d8",7952:"25381060",7966:"89fe3de1",7977:"038a9aea",7995:"44a3d6cd",8022:"830a6154",8024:"c1319d9a",8042:"5eb30971",8066:"6b319b94",8075:"a75f3295",8195:"008e7dc4",8274:"21a52936",8312:"d5e658a2",8318:"3a0452d1",8336:"97350469",8346:"6d7e8732",8456:"3a5a3a82",8474:"18cbe64a",8592:"f0e238e5",8642:"d35db63e",8726:"a121c500",8859:"bccfc802",9008:"f0fa1773",9117:"2eee603b",9118:"8e94fa1b",9137:"7c2b0059",9377:"da4649e6",9390:"9e8585c7",9492:"52afd85e",9514:"6eece132",9764:"9803d446",9793:"7ce01b30",9806:"3d3b0209",9810:"c21ac11b",9813:"c09489b1",9817:"b342e818",9827:"e6b06250",9830:"fcdf3ee1",9960:"9fe984fa",9961:"04c1525b",9973:"cc86f197"}[e]+".js",r.miniCssF=e=>{},r.g=function(){if("object"==typeof globalThis)return globalThis;try{return this||new Function("return this")()}catch(e){if("object"==typeof window)return window}}(),r.o=(e,a)=>Object.prototype.hasOwnProperty.call(e,a),c={},d="shield:",r.l=(e,a,f,b)=>{if(c[e])c[e].push(a);else{var t,o;if(void 0!==f)for(var n=document.getElementsByTagName("script"),i=0;i{t.onerror=t.onload=null,clearTimeout(s);var d=c[e];if(delete c[e],t.parentNode&&t.parentNode.removeChild(t),d&&d.forEach((e=>e(f))),a)return a(f)},s=setTimeout(u.bind(null,void 0,{type:"timeout",target:t}),12e4);t.onerror=u.bind(null,t.onerror),t.onload=u.bind(null,t.onload),o&&document.head.appendChild(t)}},r.r=e=>{"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})},r.nmd=e=>(e.paths=[],e.children||(e.children=[]),e),r.p="/shield/",r.gca=function(e){return e={57782163:"3191",58175526:"4409",79755079:"521","81799e41":"0","935f2afb":"53","063bcf8c":"154","639c8683":"258","757440e1":"559","56114c18":"591",af650176:"608","154c7c82":"613",b379a172:"627","0b1a0c1d":"629","9450a92f":"747","15bd7140":"807","5e4290c3":"849","91c76d4c":"960",a0223cec:"1001",af591bac:"1026","525e7e1c":"1045",d8dadad9:"1087","235e47fd":"1129","8b16dfca":"1157","4ebe2796":"1204",bd051426:"1303","678c4125":"1319",f78cb8d5:"1345","137afead":"1352","7cee132a":"1379","36ff4aed":"1466","122a9a0a":"1553","8444b4ba":"1575",be08f2d0:"1621","3d97ff3e":"1630",b8265ab6:"1645","939208dc":"1692",dc59a77e:"1740","4c5e977b":"1893","07fa978f":"1960",acb3a279:"1993",da2b3fe7:"1998","732169bb":"2001",ba704184:"2085","589c6686":"2141","4c441f1e":"2223","2ec705b5":"2257","1e399fa0":"2297",f16281c3:"2352","2c0852f3":"2381","1f82dfc4":"2423","0741da40":"2486","8a1d978c":"2546","7e44693c":"2557","2416e5e0":"2568",c44fb328:"2611","0b2e5fa6":"2653",addd01e7:"2734","4217aa77":"2750","3ec3f58c":"2753","6cb47c0a":"2782","7614d37a":"2819",eab61343:"2828","6e55269d":"2849","14f70d12":"2854","0a6489c4":"2861","8656d2cb":"3017","6758bc63":"3030","973f92f3":"3045",b1592759:"3068","41993d15":"3081",c1540892:"3138","3b8c55ea":"3217",a0b50537:"3226",d6375c27:"3351",a5d17473:"3523","0862b264":"3626",f1fe12d1:"3651","39c35be1":"3715","69babfcc":"3911",fb2e4ac3:"3942",e6721467:"4026",f35f9779:"4070",a09c2993:"4128","974e60fa":"4155",c592e353:"4163","2b747206":"4194","6bd67bec":"4258","79c1ef57":"4504","329028fe":"4554","90c78a7a":"4610",b314e256:"4656","38240a34":"4727","30dbb125":"4777","2a52c330":"4887",e7b14a6e:"5274","85ab9c8d":"5346",e106a72b:"5442","00e4296b":"5464","4dae9392":"5468","619ee569":"5481",b12cc002:"5640","05f89af9":"5660","15b0aad8":"5696",e9c6cd3d:"5771","9815d18f":"5873",c3547753:"5879",fdfd3bf4:"6045",b8257e6e:"6122","6a90f76b":"6179",d9e16301:"6217","0cbcb03e":"6389","8778ff6c":"6430","7c2fa695":"6453","0c9bd6d0":"6458",c91fffbe:"6622","0563b9c0":"6698","3e624669":"6726","83a85fa4":"6786","8e46894b":"6832","8a1416ba":"6886","5d7f3e2f":"6910","1a8b86dc":"6997","442db9bd":"7082","99b2a733":"7377","9470cc54":"7381","48d4592f":"7451","430ce505":"7745",c13e6886:"7825","7e62c215":"7858","971d47e0":"7888",c389f5a0:"7919","6550eba9":"7952",eb0f1f62:"7966","04e56296":"7977",fbdf8469:"7995","4fdd65ff":"8022",b064323e:"8024","89a0316a":"8042",e953480e:"8066","24e631b4":"8075",d46c5637:"8195","0d47d022":"8274","57028ef1":"8312","3041af2a":"8318","44e33a92":"8336","3bb2fad9":"8346","2c5a41d0":"8456","38f3e015":"8474",common:"8592",bfecf59d:"8642","06fd825a":"8726","16a04d33":"8859","628e1422":"9008","96fc3af1":"9117",f0c85612:"9118","399652c8":"9377",eb0d9f45:"9390","351af5fd":"9492","1be78505":"9514","0ab57e89":"9764","749f4d75":"9793","09671944":"9806","5ee7b1bc":"9810",c92f0bff:"9813","14eb3368":"9817","3f27c6d7":"9827",b9c7d324:"9830","93da10dc":"9960","84ea66e6":"9961",f019fae4:"9973"}[e]||e,r.p+r.u(e)},(()=>{var e={6552:0,532:0};r.f.j=(a,f)=>{var c=r.o(e,a)?e[a]:void 0;if(0!==c)if(c)f.push(c[2]);else if(/^(53|655)2$/.test(a))e[a]=0;else{var d=new Promise(((f,d)=>c=e[a]=[f,d]));f.push(c[2]=d);var b=r.p+r.u(a),t=new Error;r.l(b,(f=>{if(r.o(e,a)&&(0!==(c=e[a])&&(e[a]=void 0),c)){var d=f&&("load"===f.type?"missing":f.type),b=f&&f.target&&f.target.src;t.message="Loading chunk "+a+" failed.\n("+d+": "+b+")",t.name="ChunkLoadError",t.type=d,t.request=b,c[1](t)}}),"chunk-"+a,a)}},r.O.j=a=>0===e[a];var a=(a,f)=>{var c,d,b=f[0],t=f[1],o=f[2],n=0;if(b.some((a=>0!==e[a]))){for(c in t)r.o(t,c)&&(r.m[c]=t[c]);if(o)var i=o(r)}for(a&&a(f);n{"use strict";var e,a,f,c,d,b={},t={};function r(e){var a=t[e];if(void 0!==a)return a.exports;var f=t[e]={id:e,loaded:!1,exports:{}};return b[e].call(f.exports,f,f.exports,r),f.loaded=!0,f.exports}r.m=b,r.c=t,e=[],r.O=(a,f,c,d)=>{if(!f){var b=1/0;for(i=0;i=d)&&Object.keys(r.O).every((e=>r.O[e](f[o])))?f.splice(o--,1):(t=!1,d0&&e[i-1][2]>d;i--)e[i]=e[i-1];e[i]=[f,c,d]},r.n=e=>{var a=e&&e.__esModule?()=>e.default:()=>e;return r.d(a,{a:a}),a},f=Object.getPrototypeOf?e=>Object.getPrototypeOf(e):e=>e.__proto__,r.t=function(e,c){if(1&c&&(e=this(e)),8&c)return e;if("object"==typeof e&&e){if(4&c&&e.__esModule)return e;if(16&c&&"function"==typeof e.then)return e}var d=Object.create(null);r.r(d);var b={};a=a||[null,f({}),f([]),f(f)];for(var t=2&c&&e;"object"==typeof t&&!~a.indexOf(t);t=f(t))Object.getOwnPropertyNames(t).forEach((a=>b[a]=()=>e[a]));return b.default=()=>e,r.d(d,b),d},r.d=(e,a)=>{for(var f in a)r.o(a,f)&&!r.o(e,f)&&Object.defineProperty(e,f,{enumerable:!0,get:a[f]})},r.f={},r.e=e=>Promise.all(Object.keys(r.f).reduce(((a,f)=>(r.f[f](e,a),a)),[])),r.u=e=>"assets/js/"+({0:"81799e41",53:"935f2afb",154:"063bcf8c",258:"639c8683",521:"79755079",559:"757440e1",591:"56114c18",608:"af650176",613:"154c7c82",627:"b379a172",629:"0b1a0c1d",747:"9450a92f",807:"15bd7140",849:"5e4290c3",960:"91c76d4c",1001:"a0223cec",1026:"af591bac",1045:"525e7e1c",1087:"d8dadad9",1129:"235e47fd",1157:"8b16dfca",1204:"4ebe2796",1303:"bd051426",1319:"678c4125",1345:"f78cb8d5",1352:"137afead",1379:"7cee132a",1466:"36ff4aed",1553:"122a9a0a",1575:"8444b4ba",1621:"be08f2d0",1630:"3d97ff3e",1645:"b8265ab6",1692:"939208dc",1740:"dc59a77e",1893:"4c5e977b",1960:"07fa978f",1993:"acb3a279",1998:"da2b3fe7",2001:"732169bb",2085:"ba704184",2141:"589c6686",2223:"4c441f1e",2257:"2ec705b5",2297:"1e399fa0",2352:"f16281c3",2381:"2c0852f3",2423:"1f82dfc4",2486:"0741da40",2546:"8a1d978c",2557:"7e44693c",2568:"2416e5e0",2611:"c44fb328",2653:"0b2e5fa6",2734:"addd01e7",2750:"4217aa77",2753:"3ec3f58c",2782:"6cb47c0a",2819:"7614d37a",2828:"eab61343",2849:"6e55269d",2854:"14f70d12",2861:"0a6489c4",3017:"8656d2cb",3030:"6758bc63",3045:"973f92f3",3068:"b1592759",3081:"41993d15",3138:"c1540892",3191:"57782163",3217:"3b8c55ea",3226:"a0b50537",3351:"d6375c27",3523:"a5d17473",3626:"0862b264",3651:"f1fe12d1",3715:"39c35be1",3911:"69babfcc",3942:"fb2e4ac3",4026:"e6721467",4070:"f35f9779",4128:"a09c2993",4155:"974e60fa",4163:"c592e353",4194:"2b747206",4258:"6bd67bec",4409:"58175526",4504:"79c1ef57",4554:"329028fe",4610:"90c78a7a",4656:"b314e256",4727:"38240a34",4777:"30dbb125",4887:"2a52c330",5274:"e7b14a6e",5346:"85ab9c8d",5442:"e106a72b",5464:"00e4296b",5468:"4dae9392",5481:"619ee569",5640:"b12cc002",5660:"05f89af9",5696:"15b0aad8",5771:"e9c6cd3d",5873:"9815d18f",5879:"c3547753",6045:"fdfd3bf4",6122:"b8257e6e",6179:"6a90f76b",6217:"d9e16301",6389:"0cbcb03e",6430:"8778ff6c",6453:"7c2fa695",6458:"0c9bd6d0",6622:"c91fffbe",6698:"0563b9c0",6726:"3e624669",6786:"83a85fa4",6832:"8e46894b",6886:"8a1416ba",6910:"5d7f3e2f",6997:"1a8b86dc",7082:"442db9bd",7377:"99b2a733",7381:"9470cc54",7451:"48d4592f",7745:"430ce505",7825:"c13e6886",7858:"7e62c215",7888:"971d47e0",7919:"c389f5a0",7952:"6550eba9",7966:"eb0f1f62",7977:"04e56296",7995:"fbdf8469",8022:"4fdd65ff",8024:"b064323e",8042:"89a0316a",8066:"e953480e",8075:"24e631b4",8195:"d46c5637",8274:"0d47d022",8312:"57028ef1",8318:"3041af2a",8336:"44e33a92",8346:"3bb2fad9",8456:"2c5a41d0",8474:"38f3e015",8592:"common",8642:"bfecf59d",8726:"06fd825a",8859:"16a04d33",9008:"628e1422",9117:"96fc3af1",9118:"f0c85612",9377:"399652c8",9390:"eb0d9f45",9492:"351af5fd",9514:"1be78505",9764:"0ab57e89",9793:"749f4d75",9806:"09671944",9810:"5ee7b1bc",9813:"c92f0bff",9817:"14eb3368",9827:"3f27c6d7",9830:"b9c7d324",9960:"93da10dc",9961:"84ea66e6",9973:"f019fae4"}[e]||e)+"."+{0:"12cab899",53:"dd066653",70:"ec51fc24",121:"e732c399",154:"3826a6c6",258:"fbb5caf7",422:"c69e3681",521:"d9bec8ea",559:"ecff7f7e",591:"b3178ba1",608:"77f1efb6",613:"7a2396e9",627:"df14c143",629:"0bdaa4b1",747:"af9a6643",786:"0c11d2d9",807:"206aaaa0",823:"5d108ea5",849:"572e7599",932:"f6294c44",960:"fdb16066",967:"7b6d7bad",1001:"288c56c0",1011:"3a633f25",1026:"2e14197e",1045:"bd72fda4",1059:"d60c2959",1087:"f266084a",1129:"4b7ba4aa",1157:"bf1933ae",1204:"37454474",1274:"f3d2efd1",1303:"671f62e5",1319:"d4630018",1345:"3cf61c6d",1352:"110c30a3",1379:"0198cf22",1443:"8d5c8789",1466:"c776323c",1553:"33e5ea0d",1575:"fdb47103",1621:"6824b191",1630:"c7f28ca1",1645:"05fde32d",1692:"4d2e97a4",1736:"a494fbad",1740:"0583ac5f",1893:"0a97cea0",1960:"b2f09096",1993:"40dddba2",1998:"eeb52806",2001:"fe58cd7f",2085:"12c9adf9",2141:"ca836d24",2223:"63784b94",2257:"889d87ac",2297:"737fbd20",2352:"fb3a8d5c",2381:"92c4e725",2423:"79ad26b5",2444:"13a1a6c7",2486:"cb2a8f22",2494:"d188545c",2546:"e808a143",2557:"42acab2c",2568:"d7a8af24",2611:"22b294be",2653:"f58b590f",2734:"199cbf65",2750:"42d4bc78",2753:"80b49527",2782:"b04c48df",2819:"9a48f786",2828:"3c5a2429",2849:"3998f505",2854:"727c5525",2861:"88357189",3017:"87371d87",3030:"d3360b03",3045:"ba3373a2",3068:"85911bf0",3081:"0d1a6fb5",3138:"08134960",3180:"ef651182",3191:"764b3cb9",3217:"0ab8fe16",3226:"82ced913",3351:"ab03702e",3523:"6e0ef9e3",3540:"538ab423",3594:"831167a1",3626:"4aed4c75",3651:"50b2d57e",3715:"6b7e4d6f",3871:"38eb1fd5",3911:"ff874f76",3942:"21521e27",4026:"efc41b51",4070:"7f84e230",4128:"1ff92efc",4155:"73d3454d",4163:"9ec7d9a7",4194:"84c6ffbc",4258:"6f893550",4409:"6976d163",4504:"e81263c8",4554:"12b77b13",4604:"96dadf49",4610:"6fa61fa7",4656:"ded2d0ba",4727:"816c463c",4777:"36127841",4887:"442c5835",4972:"a5eddc14",5274:"dd7329dd",5346:"700bf39d",5397:"7b3da98e",5442:"3d13e5aa",5464:"617c5446",5468:"57add63c",5481:"2fbdceaf",5640:"02a7e01a",5660:"ef1f9327",5696:"cc8c528a",5771:"284c2a47",5815:"79e381cd",5873:"feb8ed3b",5879:"ee888fcd",5883:"efbd6263",6045:"d2bd838a",6122:"8cdada41",6179:"3db7d7b7",6217:"851ad904",6305:"7720ae64",6389:"f5a5cebb",6430:"9691ae7d",6453:"3f019964",6458:"fd882918",6622:"7c731dc9",6698:"68e11e46",6726:"90e21389",6786:"9ee3c3c9",6788:"ec751b73",6832:"3e953144",6886:"d87882dd",6910:"38de56a0",6942:"5de8f085",6997:"d45a282e",7064:"ff4bf31c",7082:"31dc04ea",7377:"5054ae83",7381:"e09aef96",7451:"a388e253",7745:"78b814b9",7825:"24eeaa4e",7858:"1d01e735",7888:"bf815af6",7919:"1c6862d8",7952:"25381060",7966:"89fe3de1",7977:"038a9aea",7995:"44a3d6cd",8022:"830a6154",8024:"c1319d9a",8042:"5eb30971",8066:"6b319b94",8075:"a75f3295",8195:"008e7dc4",8274:"21a52936",8312:"d5e658a2",8318:"3a0452d1",8336:"97350469",8346:"6d7e8732",8456:"3a5a3a82",8474:"18cbe64a",8592:"f0e238e5",8642:"d35db63e",8726:"a121c500",8859:"bccfc802",9008:"f0fa1773",9117:"2eee603b",9118:"8e94fa1b",9137:"7c2b0059",9377:"da4649e6",9390:"9e8585c7",9492:"52afd85e",9514:"6eece132",9764:"9803d446",9793:"7ce01b30",9806:"3d3b0209",9810:"c21ac11b",9813:"c09489b1",9817:"b342e818",9827:"e6b06250",9830:"fcdf3ee1",9960:"9fe984fa",9961:"04c1525b",9973:"cc86f197"}[e]+".js",r.miniCssF=e=>{},r.g=function(){if("object"==typeof globalThis)return globalThis;try{return this||new Function("return this")()}catch(e){if("object"==typeof window)return window}}(),r.o=(e,a)=>Object.prototype.hasOwnProperty.call(e,a),c={},d="shield:",r.l=(e,a,f,b)=>{if(c[e])c[e].push(a);else{var t,o;if(void 0!==f)for(var n=document.getElementsByTagName("script"),i=0;i{t.onerror=t.onload=null,clearTimeout(s);var d=c[e];if(delete c[e],t.parentNode&&t.parentNode.removeChild(t),d&&d.forEach((e=>e(f))),a)return a(f)},s=setTimeout(u.bind(null,void 0,{type:"timeout",target:t}),12e4);t.onerror=u.bind(null,t.onerror),t.onload=u.bind(null,t.onload),o&&document.head.appendChild(t)}},r.r=e=>{"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})},r.nmd=e=>(e.paths=[],e.children||(e.children=[]),e),r.p="/shield/",r.gca=function(e){return e={57782163:"3191",58175526:"4409",79755079:"521","81799e41":"0","935f2afb":"53","063bcf8c":"154","639c8683":"258","757440e1":"559","56114c18":"591",af650176:"608","154c7c82":"613",b379a172:"627","0b1a0c1d":"629","9450a92f":"747","15bd7140":"807","5e4290c3":"849","91c76d4c":"960",a0223cec:"1001",af591bac:"1026","525e7e1c":"1045",d8dadad9:"1087","235e47fd":"1129","8b16dfca":"1157","4ebe2796":"1204",bd051426:"1303","678c4125":"1319",f78cb8d5:"1345","137afead":"1352","7cee132a":"1379","36ff4aed":"1466","122a9a0a":"1553","8444b4ba":"1575",be08f2d0:"1621","3d97ff3e":"1630",b8265ab6:"1645","939208dc":"1692",dc59a77e:"1740","4c5e977b":"1893","07fa978f":"1960",acb3a279:"1993",da2b3fe7:"1998","732169bb":"2001",ba704184:"2085","589c6686":"2141","4c441f1e":"2223","2ec705b5":"2257","1e399fa0":"2297",f16281c3:"2352","2c0852f3":"2381","1f82dfc4":"2423","0741da40":"2486","8a1d978c":"2546","7e44693c":"2557","2416e5e0":"2568",c44fb328:"2611","0b2e5fa6":"2653",addd01e7:"2734","4217aa77":"2750","3ec3f58c":"2753","6cb47c0a":"2782","7614d37a":"2819",eab61343:"2828","6e55269d":"2849","14f70d12":"2854","0a6489c4":"2861","8656d2cb":"3017","6758bc63":"3030","973f92f3":"3045",b1592759:"3068","41993d15":"3081",c1540892:"3138","3b8c55ea":"3217",a0b50537:"3226",d6375c27:"3351",a5d17473:"3523","0862b264":"3626",f1fe12d1:"3651","39c35be1":"3715","69babfcc":"3911",fb2e4ac3:"3942",e6721467:"4026",f35f9779:"4070",a09c2993:"4128","974e60fa":"4155",c592e353:"4163","2b747206":"4194","6bd67bec":"4258","79c1ef57":"4504","329028fe":"4554","90c78a7a":"4610",b314e256:"4656","38240a34":"4727","30dbb125":"4777","2a52c330":"4887",e7b14a6e:"5274","85ab9c8d":"5346",e106a72b:"5442","00e4296b":"5464","4dae9392":"5468","619ee569":"5481",b12cc002:"5640","05f89af9":"5660","15b0aad8":"5696",e9c6cd3d:"5771","9815d18f":"5873",c3547753:"5879",fdfd3bf4:"6045",b8257e6e:"6122","6a90f76b":"6179",d9e16301:"6217","0cbcb03e":"6389","8778ff6c":"6430","7c2fa695":"6453","0c9bd6d0":"6458",c91fffbe:"6622","0563b9c0":"6698","3e624669":"6726","83a85fa4":"6786","8e46894b":"6832","8a1416ba":"6886","5d7f3e2f":"6910","1a8b86dc":"6997","442db9bd":"7082","99b2a733":"7377","9470cc54":"7381","48d4592f":"7451","430ce505":"7745",c13e6886:"7825","7e62c215":"7858","971d47e0":"7888",c389f5a0:"7919","6550eba9":"7952",eb0f1f62:"7966","04e56296":"7977",fbdf8469:"7995","4fdd65ff":"8022",b064323e:"8024","89a0316a":"8042",e953480e:"8066","24e631b4":"8075",d46c5637:"8195","0d47d022":"8274","57028ef1":"8312","3041af2a":"8318","44e33a92":"8336","3bb2fad9":"8346","2c5a41d0":"8456","38f3e015":"8474",common:"8592",bfecf59d:"8642","06fd825a":"8726","16a04d33":"8859","628e1422":"9008","96fc3af1":"9117",f0c85612:"9118","399652c8":"9377",eb0d9f45:"9390","351af5fd":"9492","1be78505":"9514","0ab57e89":"9764","749f4d75":"9793","09671944":"9806","5ee7b1bc":"9810",c92f0bff:"9813","14eb3368":"9817","3f27c6d7":"9827",b9c7d324:"9830","93da10dc":"9960","84ea66e6":"9961",f019fae4:"9973"}[e]||e,r.p+r.u(e)},(()=>{var e={6552:0,532:0};r.f.j=(a,f)=>{var c=r.o(e,a)?e[a]:void 0;if(0!==c)if(c)f.push(c[2]);else if(/^(53|655)2$/.test(a))e[a]=0;else{var d=new Promise(((f,d)=>c=e[a]=[f,d]));f.push(c[2]=d);var b=r.p+r.u(a),t=new Error;r.l(b,(f=>{if(r.o(e,a)&&(0!==(c=e[a])&&(e[a]=void 0),c)){var d=f&&("load"===f.type?"missing":f.type),b=f&&f.target&&f.target.src;t.message="Loading chunk "+a+" failed.\n("+d+": "+b+")",t.name="ChunkLoadError",t.type=d,t.request=b,c[1](t)}}),"chunk-"+a,a)}},r.O.j=a=>0===e[a];var a=(a,f)=>{var c,d,b=f[0],t=f[1],o=f[2],n=0;if(b.some((a=>0!==e[a]))){for(c in t)r.o(t,c)&&(r.m[c]=t[c]);if(o)var i=o(r)}for(a&&a(f);n - + @@ -68,7 +68,7 @@ private key that matches the public key stored in the database. Also known as JWT grant.

Shield can also return a token that the service can use to access the resource instead of using their credentials on every request. This token is called a bearer access token. The service then sends the access token with every request to the resource. Use of access token is optional, and it is short-lived.

Open DataOps Foundation © 2023
- + \ No newline at end of file diff --git a/authn/serviceuser/index.html b/authn/serviceuser/index.html index 7ae9c3e1d..208afd2fb 100644 --- a/authn/serviceuser/index.html +++ b/authn/serviceuser/index.html @@ -7,7 +7,7 @@ - + @@ -30,7 +30,7 @@ in various part of the infrastructure to verify the request. It can be passed along the request in services behind the shield server and all of them only need to validate it using shield server's public key. Access token endpoint is available at /v1beta1/auth/token.

Open DataOps Foundation © 2023
- + \ No newline at end of file diff --git a/authn/user/index.html b/authn/user/index.html index 904cabbc5..1bf9d9550 100644 --- a/authn/user/index.html +++ b/authn/user/index.html @@ -7,7 +7,7 @@ - + @@ -49,7 +49,7 @@ using the RS256 signing algorithm. Shield generated access token can be validated using the public key of the RSA key pair. The public key can be fetched from the Shield server from the endpoint /.well-known/jwks.json.

note

The key set can contain more than one key and is uniquely identified by the kid field. The JWT contains the kid field in the header which is used to identify the key used to sign the JWT.

Open DataOps Foundation © 2023
- + \ No newline at end of file diff --git a/authz/example/index.html b/authz/example/index.html index b13d2ad6f..e299d774f 100644 --- a/authz/example/index.html +++ b/authz/example/index.html @@ -7,13 +7,13 @@ - +

Example of Authorization via Shield

Raystack Store​

Let's assume Shield contains a user name John Doe who creates an organization called Raystack Store with a project called Financials inside it.

Using the Create Permissions API a Shield Admin can create the permissions with the following keys:

  1. storage.file.get : Allows retrieving files from storage.
  2. storage.file.delete : Allows deleting files from storage.
  3. storage.file.post : Allows posting or uploading files to storage.

And roles for storage service can be created using Create Roles API or Create Org Roles. For example, the following roles can be defined:

  1. storage file owner: Grants full ownership and control over the files.
  2. storage file reader: Allows reading or accessing files.

Using the Create Resource API John Doe can create a file in the Financials project with resource name as sensitive-info.txt which contains Raystack Store's previous quarter financial details.

Assuming in Shield, there also exists a user named Jane Doe who is a member of Raystack Store. In case John wants his accountant, Jane to get access to this file for verification, he can create a Policy in Shield using Create Policy API with role of a storage file reader and providing the resource details storage/file:92f69c3a-334b-4f25-90b8-4d4f3be6b825 in format resource's namespace:uuid.

To check if Jane has access to the sensitive-info.txt file, you can utilize the Check API and verify if the user has read access to the file or not. This check will confirm whether Jane has the necessary permissions to view the contents of the file.

Open DataOps Foundation © 2023
- + \ No newline at end of file diff --git a/authz/overview/index.html b/authz/overview/index.html index a3391126e..7b3e87cf9 100644 --- a/authz/overview/index.html +++ b/authz/overview/index.html @@ -7,7 +7,7 @@ - + @@ -34,7 +34,7 @@ SpiceDB->>App: Valid Permission App-->>User: Return Resource end

SpiceDB is Authzed's open source Google Zanzibar inspired permission system which is capable of answering the question like

does <User> have <permission> on <resource>?

Permissions are defined as relationships between Users and resources. A User can be a user, a group, or any other entity that needs to be granted permissions. A resource can be a file, a database, or any other object that needs to be protected.

The SpiceDB permissions system works by first creating a permissions schema that defines the relationships between Users and resources. The relationships between resources and Users used for permissions checks are stored within SpiceDB's data store. The schema is then used to create a graph of permissions, where each node in the graph represents a User or resource, and each edge in the graph represents a permission.

When a permission check is performed, SpiceDB traverses the permissions graph to determine whether the User has the required permission to access the resource.

Open DataOps Foundation © 2023
- + \ No newline at end of file diff --git a/authz/permission/index.html b/authz/permission/index.html index 89cef4990..36dad144f 100644 --- a/authz/permission/index.html +++ b/authz/permission/index.html @@ -7,14 +7,14 @@ - +

Permissions

Permissions represent rules that define what actions or operations a user or identity can perform on specific resources. Permissions help enforce security and access control by governing the level of access granted to individuals or groups.

Each predefined permission has a specific purpose and grants a defined level of access to a particular resource or service. By assigning these permissions to users, groups, or service accounts, administrators can effectively control and manage access to an organization resources. Permissions are assigned to roles such that each role is essentially a group of permissions. Each user has one or more roles that define what the user can do.

Each Shield deployment is populated with predefined permissions which allow users to perform common operations such as listing, getting, creating, updating, and deleting entities at different levels of the platform's hierarchy. They also include more specialized permissions like role management, policy management, and acceptance of invitations.

Each permission is attached to a logical partition in Shield called Namespace.

Namespace​

A Namespace in Shield is a logical container or partitioning mechanism that helps organize and manage resources and access control policies. It is used to group related entities and define the scope of authorization within a system. With the namespaces we compartmentalize and control access to different parts of the application or system, allowing more granular authorization and improved security.

Each namespace can have its own set of permissions, roles, and access control policies, enabling fine-grained control over who can access what resources within the defined scope. For example, the namespace app/organization in Shield contains permissions related to managing organizations. These permissions could include create update delete get and so on.

Predefined Org Permissions​

Includes a list of Shield's predefined permissions at the organization level.

info

Shield allows inheritance of permissions for a hierarchical structure, where higher-level permissions grant access to lower-level entities. In this case, granting permissions at the organization level automatically extends those permissions to the projects, resources, and groups within that org.

Permission TitleDescriptionPermission NameNamespace
Organization AdministerGrants administrative privileges for managing the organization.administerapp/organization
Organization DeleteAllows deleting the organization.deleteapp/organization
Organization UpdateAllows updating or modifying the organization's information.updateapp/organization
Organization GetAllows retrieving or accessing a specific organization.getapp/organization
Organization Role ManageEnables managing or controlling roles within the organization.rolemanageapp/organization
Organization Policy ManageEnables managing or controlling access control policies within the organization.policymanageapp/organization
Organization Project ListAllows listing or retrieving a list of projects within the organization.projectlistapp/organization
Organization Group ListAllows listing or retrieving a list of groups within the organization.grouplistapp/organization
Organization Invitation ListAllows listing or retrieving a list of user invitations in the organization.invitationlistapp/organization
Organization Project CreateAllows creating new projects within the organization.projectcreateapp/organization
Organization Group CreateAllows creating new groups within the organization.groupcreateapp/organization
Organization Invitation CreateAllows creating new invitations or access requests within the organization.invitationcreateapp/organization

Predefined Project Permissions​

Includes a list of Shield's predefined permissions at the project level.

Permission TitleDescriptionPermission NameNamespace
Project AdministerGrants administrative privileges for managing the project.administerapp/project
Project DeleteAllows deleting the project.deleteapp/project
Project UpdateAllows updating or modifying the project's information.updateapp/project
Project GetAllows retrieving or accessing a specific project.getapp/project
Project Policy ManageEnables managing or controlling access control policies within the project.policymanageapp/project
Project Resource ListAllows listing or retrieving a list of resources within the project.resourcelistapp/project

Predefined Group Permissions​

Contains a list of Shield's predefined permissions at the group level.

Permission TitleDescriptionNamespacePermission Name
Group AdministerGrants administrative privileges for managing the group.administerapp/group
Group DeleteAllows deleting the group.deleteapp/group
Group UpdateAllows updating or modifying the group's information.updateapp/group
Group GetAllows retrieving or accessing a specific group.getapp/group
note

Permissions in Shield follow a hierarchical structure, where higher-level permissions include the capabilities of lower-level permissions. For example, a higher-level permission like adminiter includes all the capabilities of a lower-level permission like get.

Custom Permissions​

Shield allow the its platform administrators (Superusers) to create permissions to meet specific authorization requirements beyond the predefined set of permissions. Custom permissions allow for more granular control over access to resources and actions within an application or system. They enable organizations to define and enforce fine-grained access policies tailored to their unique needs.

When creating custom permissions, administrators typically define the name and scope (namespace) of the permission. The name should be descriptive and indicative of the action or resource it governs. The scope determines where the permission applies, such as the platform(making it available across all the organizations in Shield), organization, project or group.

note

The permissions can either be created dynamically when the Shield is running, or can either be provided in the server configurations.

For example, let's say you have an e-commerce application where users can manage their shopping carts. To control access to cart-related actions, you can create custom permissions in the potato/cart namespace.

Sample custom permission requirements:

Permission NamePermission TitleNamespaceDescription
deleteCart Deletepotato/cartGrants the ability to delete items from the shopping cart.
updateCart Updatepotato/cartAllows updating the contents of the shopping cart.
getCart Getpotato/cartEnables retrieving the details of the shopping cart.

This is how the resource config file will look like

info

While creating permissions, it is important to note that the namespace is appended to the permission name to generate a permission slug. For instance, the delete permission name will be appended with namespace potato/cart, to generate the final permission slug as potato_cart_delete in Shield. This naming convention is used to ensure uniqueness and organization of permissions within Shield. While creating a role, we pass the list of these permission slugs being binded to that role.

Managing Permission​

tip

Some of these APIs require special privileges to access these endpoints and to authorize these requests, users may need a Client ID/Secret or an Access token to proceed. Read Authorization for APIs to learn more.

Open DataOps Foundation © 2023
- + \ No newline at end of file diff --git a/authz/policy/index.html b/authz/policy/index.html index 79c0e8d68..c8f968713 100644 --- a/authz/policy/index.html +++ b/authz/policy/index.html @@ -7,13 +7,13 @@ - +

Policy

Policies define the permissions and access control rules that govern user access to resources within the Shield platform. By configuring policies, you can control and manage the level of access granted to users, groups, or service accounts.

A policy in Shield consists of a set of permissions associated with a role. The role determines the actions that a user can perform on specific resources.

Policy Usage​

Shield internally creates a SpiceDB relation between the Subject(Principal) and Object(Resource, Org, Project, Group) whenever a policy is created in Shield. And when a user tries to access the resource, the Shield looks up SpiceDB to check if a given relation has a specified permission. Thus, whenever a request is made for accessing a resource in Shield, SpiceDB evaluates the defined policies and permissions to determine if the request is authorized. It checks the relationships, roles, and permissions associated with the requested resource and the user making the request. If the conditions specified in the policies are satisfied, access is granted; otherwise, access is denied.

Check API​

To check if the current logged in user has the permission to access a particular resource, Shield provides the Check API. The check API in Shield works with policy for authorization by using the following steps:

  1. The user sends a request to the check API with the following information:
    i. The resource they want to check
    ii. The action they want to perform on the resource

  2. The check API queries the SpiceDB engine to determine if the user is authorized to perform the requested action on the resource.

  3. The check API returns a response to the user indicating whether or not they are authorized to perform the requested action on the resource.

Getting current user's credentials: The principal crendentials required to authorize the user is obtained from the current logged in user's session (if available). Otherwise, the client ID and secret or access token from the request headers can also be used to validate the user request to access the resource.

Sample Query​

curl -L -X POST 'http://127.0.0.1:7400/v1beta1/check' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic dGVzdC1jbGllbnQtaWQ6dGVzdC1zZWNyZXQ=' \
--data-raw '{
  "permission": "get",
  "resource": "compute/instance:92f69c3a-334b-4f25-90b8-4d4f3be6b825"
}'
info

The resource field should contain the resource namespace and resource id/name in this format namespace:uuid or namespace:name.

Instead of passing complete namespaces for organization and projects, one can also use the aliases of org, organization or project instead of app/organization and app/project.

Similarly, instead of passing the unique UUID for the organization or project, one can pass the unique organization or project name used while creating these resources.

In case the object is not an organization or project, it can be a project resource and one can use format of namespace:uuid or namespace:urn in the resource field above.

Open DataOps Foundation © 2023
- + \ No newline at end of file diff --git a/authz/role/index.html b/authz/role/index.html index a3194bf42..39c82fb8e 100644 --- a/authz/role/index.html +++ b/authz/role/index.html @@ -7,7 +7,7 @@ - + @@ -15,7 +15,7 @@

Roles

A Role is a collection of permissions in Shield. Roles are typically associated with one or more policies, which specify the permissions granted to the users. When a user is assigned a role, they inherit the permissions defined within that role. This simplifies access management by allowing administrators to assign roles to users rather than individually assigning permissions.

Roles in Shield is used to implement the Role based acces control (RBAC)

Predefined Roles​

Role NamePermissionsDescription
app_organization_ownerapp_organization_administerGrants administrative privileges for managing the organization and all the projects, groups and users under it.
app_organization_managerapp_organization_update
app_organization_get		Allows updating and retrieving organization information including its resources.
app_organization_viewerapp_organization_getAllows retrieving or viewing a specific organization and its underlying resources.
app_project_ownerapp_project_administerGrants administrative privileges for managing the project.
app_project_managerapp_project_update
app_project_get
app_organization_projectcreate
app_organization_projectlist		Allows updating, retrieving project information, creating and listing organization projects
app_project_viewerapp_project_getAllows retrieving or accessing a specific project.
app_group_ownerapp_group_administerGrants administrative privileges for managing the group.

Besides this a Shield Superuser can add custom roles at a particular namespace if required.

Deactivate and Reactivate a role​

In Shield, a role can be disabled when it needs to be temporarily or permanently deactivated. Disabling a role restricts users assigned to that role from exercising the permissions associated with it. A role can be disabled due to policy or regulatory compliance violations, temporary suspensions during investigations or disciplinary actions, or security concerns regarding potential compromise or misuse. If there are security concerns surrounding a role, such as suspected compromise or misuse, disabling the role immediately revokes the associated permissions, mitigating potential risks and safeguarding the system and its resources.

Deleting a role​

danger

Caution should be exercised when deleting a role, as it cannot be undone. Deleting a Role is fatal as it permanently removes the role and the all associated policies created for granting a role to a principal. Users will not be able to perform any actions or access any resources that are associated with the deleted role.

Custom Roles and How to use the roles for access control​

In continuation of example from custom permissions in the previous page, let's see how the bird's eye view of how we will create custom roles and attach it to a principal in Shield.

To start using Shield Roles, follow these steps:

  1. Define Roles: Identify the different roles you need in your system. Think about the specific sets of permissions each role should have.

    For example, you might have roles like CartAdmin, CartManager and CartUser each with different levels of access to our e-commerce shopping carts.

  2. Create Custom Permissions: If the predefined permissions in Shield do not meet your requirements, you can create custom permissions. Custom permissions allow you to define granular access control tailored to your application's needs.

  3. Assign Permissions to Roles: Once you have defined the roles and permissions, assign the appropriate permissions to each role. Consider the specific actions and resources each role should have access to.

    For example, CartManager will have potato_cart_update and potato_cart_get permissions from the previous example for managing our e-commerce shopping cart.

  4. Assign Roles to Users or Groups via Policy: Finally, assign roles to individual users or groups. This determines the access rights and privileges for each user or group in your org. Users inherit the permissions associated with the roles they are assigned. We will read more on this in the next pages.

note

Shield superusers can create a custom role platform wide which mean this role will be visible in all the organizations in the Shield instance. Shield also provides flexibility to Org Admins to create a custom role specific to the organization.

Managing Roles​

FieldTypeDescription
iduuidUnique Role identifier
namestringThe name of the role. The name must be unique within the entire Shield instance. The name can contain only alphanumeric characters, dashes and underscores.
Example:"app_organization_owner"
titlestringThe title can contain any UTF-8 character, used to provide a human-readable name for the organization. Can also be left empty.
Example: "Organization Owner"
permissionsstring[]List of permission slugs to be assigned to the role
Example: ["app_organization_administer"]
metadataobjectMetadata object for organizations that can hold key value pairs defined in Role Metaschema. The default Role Metaschema contains labels and descripton fields. Update the Organization Metaschema to add more fields.
Example:{"labels": {"key": "value"}, "description": "Role description"}
orgIdstringUnique Organization identifier to which the role is attached
statestringRepresents the status of the role indicating whether it can be used in a policy or not. One of enabled or disabled
tip

Some of these APIs require special privileges to access these endpoints and to authorize these requests, users may need a Client ID/Secret or an Access token to proceed. Read Authorization for APIs to learn more.

List Organization Roles​

To get a list of custom roles created under an organization with their associated permissions. Note the default roles avaliable across the Shield platform and inherited in every organizations wont be displayed with this

  1. Using GET /v1beta1/organizations/:orgId/roles API. One can also filter with an optional parameter for role status
$ curl -L -X GET 'http://127.0.0.1:7400/v1beta1/organizations/4d726cf5-52f6-46f1-9c87-1a79f29e3abf/roles?state=enabled' \
-H 'Accept: application/json'

List Default Roles (Across Platform)​

To get the list of all the predefined roles in Shield use the GET /v1beta1/roles API. You can additionally filter the results with an optional parameter for role status. Note: these default roles are avaliable across all the organizations in Shield (platform wide).

$ curl -L -X GET 'http://127.0.0.1:7400/v1beta1/roles?state=enabled' \
-H 'Accept: application/json'

Create organization role​

Create a custom role under an organization. This custom role will only be available for assignment to the principals within the organization.

Using the POST /v1beta1/organizations/:orgId/roles API we can create a custom org role like this:

$ curl -L -X POST 'http://127.0.0.1:7400/v1beta1/organizations/4d726cf5-52f6-46f1-9c87-1a79f29e3abf/roles' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
--data-raw '{
  "name": "manager",
  "permissions": [
    "potato_cart_update",
    "potato_cart_get"
  ],
  "metadata": {},
  "title": "Cart Manager"
}'

Update organization role​

Update a custom role under an organization using PUT /v1beta1/organizations/:orgId/roles/:id API. Lets update the permissions of the Cart Manager role we created in the previous example.

curl -L -X PUT 'http://127.0.0.1:7400/v1beta1/organizations/4d726cf5-52f6-46f1-9c87-1a79f29e3abf/roles/c2d85306-96f4-4895-98b4-c3e5c2f3084d' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
--data-raw '{
  "name": "manager",
  "permissions": [
    "potato_cart_update",
    "potato_cart_get",
    "potato_cart_delete"
  ],
  "metadata": {},
  "title": "Cart Manager"
}'

Delete Organization Role​

Delete a custom role in an organization will also delete all the policies assocaited with the role being deleted. One can do this using DELETE /v1beta1/organizations/:orgId/roles/:id API.

curl -L -X DELETE 'http://127.0.0.1:7400/v1beta1/organizations/4d726cf5-52f6-46f1-9c87-1a79f29e3abf/roles/c2d85306-96f4-4895-98b4-c3e5c2f3084d' \
-H 'Accept: application/json'
Open DataOps Foundation © 2023
- + \ No newline at end of file diff --git a/category/apis/authn/index.html b/category/apis/authn/index.html index 892fcd307..3c9899768 100644 --- a/category/apis/authn/index.html +++ b/category/apis/authn/index.html @@ -7,13 +7,13 @@ - +

Authn

Open DataOps Foundation © 2023
- + \ No newline at end of file diff --git a/category/apis/authz/index.html b/category/apis/authz/index.html index bbb8b6141..d8e434458 100644 --- a/category/apis/authz/index.html +++ b/category/apis/authz/index.html @@ -7,13 +7,13 @@ - +
Open DataOps Foundation © 2023
- + \ No newline at end of file diff --git a/category/apis/group/index.html b/category/apis/group/index.html index 60e1a4e4e..f13238c0a 100644 --- a/category/apis/group/index.html +++ b/category/apis/group/index.html @@ -7,13 +7,13 @@ - +

Group

Open DataOps Foundation © 2023
- + \ No newline at end of file diff --git a/category/apis/meta-schema/index.html b/category/apis/meta-schema/index.html index 5e7fd2610..7239896c4 100644 --- a/category/apis/meta-schema/index.html +++ b/category/apis/meta-schema/index.html @@ -7,13 +7,13 @@ - +

MetaSchema

Open DataOps Foundation © 2023
- + \ No newline at end of file diff --git a/category/apis/namespace/index.html b/category/apis/namespace/index.html index f0abe0f6e..3a064474f 100644 --- a/category/apis/namespace/index.html +++ b/category/apis/namespace/index.html @@ -7,13 +7,13 @@ - +
Open DataOps Foundation © 2023
- + \ No newline at end of file diff --git a/category/apis/organization/index.html b/category/apis/organization/index.html index 9961debbf..9e6024315 100644 --- a/category/apis/organization/index.html +++ b/category/apis/organization/index.html @@ -7,13 +7,13 @@ - +

Organization

Open DataOps Foundation © 2023
- + \ No newline at end of file diff --git a/category/apis/permission/index.html b/category/apis/permission/index.html index 651ad96eb..20a7fefa0 100644 --- a/category/apis/permission/index.html +++ b/category/apis/permission/index.html @@ -7,13 +7,13 @@ - +
Open DataOps Foundation © 2023
- + \ No newline at end of file diff --git a/category/apis/policy/index.html b/category/apis/policy/index.html index 114877eb4..5757ef0ef 100644 --- a/category/apis/policy/index.html +++ b/category/apis/policy/index.html @@ -7,13 +7,13 @@ - +
Open DataOps Foundation © 2023
- + \ No newline at end of file diff --git a/category/apis/project/index.html b/category/apis/project/index.html index 487f9fcb0..a7b5de26f 100644 --- a/category/apis/project/index.html +++ b/category/apis/project/index.html @@ -7,13 +7,13 @@ - +
Open DataOps Foundation © 2023
- + \ No newline at end of file diff --git a/category/apis/relation/index.html b/category/apis/relation/index.html index f69b4d0fd..dd71acd32 100644 --- a/category/apis/relation/index.html +++ b/category/apis/relation/index.html @@ -7,13 +7,13 @@ - +
Open DataOps Foundation © 2023
- + \ No newline at end of file diff --git a/category/apis/resource/index.html b/category/apis/resource/index.html index 03bef7642..89bd17b66 100644 --- a/category/apis/resource/index.html +++ b/category/apis/resource/index.html @@ -7,13 +7,13 @@ - +
Open DataOps Foundation © 2023
- + \ No newline at end of file diff --git a/category/apis/role/index.html b/category/apis/role/index.html index 395d1d3bb..d29cd3093 100644 --- a/category/apis/role/index.html +++ b/category/apis/role/index.html @@ -7,13 +7,13 @@ - +

Role

Open DataOps Foundation © 2023
- + \ No newline at end of file diff --git a/category/apis/service-user/index.html b/category/apis/service-user/index.html index 84a63294f..162fd2685 100644 --- a/category/apis/service-user/index.html +++ b/category/apis/service-user/index.html @@ -7,13 +7,13 @@ - +

ServiceUser

Open DataOps Foundation © 2023
- + \ No newline at end of file diff --git a/category/apis/user/index.html b/category/apis/user/index.html index 8615a154b..7e7b0fa62 100644 --- a/category/apis/user/index.html +++ b/category/apis/user/index.html @@ -7,13 +7,13 @@ - +

User

📄️ Create user

Create a user with the given details. A user is not attached to an organization or a group by default,and can be invited to the org/group. The name of the user must be unique within the entire Shield instance. If a user name is not provided, Shield automatically generates a name from the user email. The user metadata is validated against the user metaschema. By default the user metaschema contains `labels` and `descriptions` for the user. The `title` field can be optionally added for a user-friendly name. <br/><br/>*Example:*`{'email':'john.doe@raystack.org','title':'John Doe',metadata:{'label': {'key1': 'value1'}, 'description': 'User Description'}}`

Open DataOps Foundation © 2023
- + \ No newline at end of file diff --git a/concepts/architecture/index.html b/concepts/architecture/index.html index d3cd7b64f..8000ba5d4 100644 --- a/concepts/architecture/index.html +++ b/concepts/architecture/index.html @@ -7,7 +7,7 @@ - + @@ -18,7 +18,7 @@ There are a few different middlewares which are rule-matching, prefix, basic_auth, attribute and authz. We'll discuss each one in details in the upcoming sections.

  • Hook: Hooks are engaged after a response is received form the backend service. Currently we just have a single resource creation hook named authz.

    • Let's have a look at the Shield's Architecture where we will also be discussing about the different middlewares and hoooks.

    Shield Proxy Architecture​

    Shield Proxy Architecture

    Sheild's proxy is build from two major components which are middlewares and hooks. Let's dive deeper into each of these components.

    Middleware​

    Middlewares in shield have the following interface. 

    type Middleware interface {
        Info() *MiddlewareInfo
        ServeHTTP(rw http.ResponseWriter, req *http.Request)
    }

    type MiddlewareInfo struct {
        Name        string
        Description string
    }

    Shield is designed to execute the middlewares in a fixed order maintained by a stack. The order followed is

    • Rule match
    • Attributes
    • Basic auth
    • Authz
    • Prefix

    Rule match​

    The rule match middleware finds the rule configured for a path and enriches the ctx with it. It also enriched the ctx with the request body.

    Attributes​

    The attributes middleware builds a map of the attributes passed and enriches the ctx with it.

    Basic auth​

    This middleware can be configured to support basic authentication with shield.

    Authz​

    This middleware checks in the SpiceDB if the user is authorized with atleast one (OR operation) the permissions.

    Prefix​

    This middleware strips a configured prefix from the request's URL path.

    Hook​

    Hooks in shield have the following interface.

    type Service interface {
        Info() Info
        ServeHook(res *http.Response, err error) (*http.Response, error)
    }

    Shield only have a single hook

    • Authz

    Authz​

    Authz hook persists the resource been created in the configfured backencd in Shield's DB. It does not create any relation by default but relations can be configured too. The relashions are created and stored both in Shield's DB and SpiceDB.

    Open DataOps Foundation © 2023
    - + \ No newline at end of file diff --git a/concepts/glossary/index.html b/concepts/glossary/index.html index 08309b06a..0b2891448 100644 --- a/concepts/glossary/index.html +++ b/concepts/glossary/index.html @@ -7,14 +7,14 @@ - +

    Glossary

    Terminology and concepts used in Shield documentation.

    Access Token​

    An access token is a credential which serves as proof of authentication and authorisation to access protected resources in a system or an API. After successful authorisation, an access token is included in the headers or parameters of API requests to validate the user's identity and permissions. The access token contains information such as the client's identity and the permissions granted to it. The server validates the access token to determine if the client is authorised to access the requested resource.

    Backend​

    External Service which wants to use Shield for authz. It can verify access via Shield Proxy & API.

    Client ID​

    The Client ID is a public identifier assigned to a client application by the authorization server. It is typically known to the server and can be shared openly. It helps identify the client application when making requests to the authorization server.

    Client Secret​

    The Client Secret is a confidential string or password associated with the client application. It is meant to be kept confidential and only known to the client application and the OAuth identity provider. The Client Secret adds an extra layer of security by ensuring that only authorized client applications can access protected resources.

    Identity Providers (IdPs)​

    Shield supports integration with external identity providers through OpenID Connect (OIDC). This enables users to authenticate using their existing credentials from external systems, such as Google accounts, Microsoft Azure AD, or Github. The authentication process is handled by the respective IdP, while Shield handles the subsequent authorization based on the authenticated identity.

    Issuer URL​

    The Issuer URL in OIDC (OpenID Connect) is the URL that uniquely identifies the identity provider (IdP) or an authorization server. It serves as a reference point for the OIDC client to discover and retrieve necessary information about the IdP's configuration and supported endpoints. To find the Issuer URL for an OIDC provider, you typically need to refer to the provider's documentation or specifications.

    JWT Token​

    A JSON Web Token(JWT) is a specific type of access token that is encoded as a JSON object and conforms to the JWT standard. It is a self-contained token that includes the user's identity and any additional claims or information as a JSON payload. The JWT is digitally signed by the issuer (usually an authorization server) to ensure its integrity and authenticity. JWTs are commonly used in modern authentication and authorization protocols, such as OAuth 2.0 and OpenID Connect.

    Namespace​

    Type of objects over which we want authorization. They are of two types:

    1. System Namespace: Objects like Organization, Project & Team, over which we need authorization to actions such as adding user to team, adding user as owner of project.

    2. Resource Namespace: Resources Types over which we need authorization. For example, we need edit & view permissions over GCE Instances.

    OIDC​

    OpenID Connect (or OIDC) is an identity layer built on top of the OAuth 2.0 protocol that enables clients (applications) to verify the identity of end-users based on authentication performed by an authorization server.

    Organization​

    An Organization is a top-level resource in Shield. Each Project, Role, Group, Policy and Principal belongs to an organization. Each organization will represent a single tenant in your SaaS application.

    Permission​

    Ability to carry out any action, in Shield or configured Backends.

    Policy​

    It defines the specific actions that are allowed or denied on resources. Aliter, Policies are used to enforce authorization and access control by binding one or more principals to individual roles. Policies can be attached to users, groups, or roles to grant or restrict access to resources.

    Principal​

    Principal refers to an entity that can be authenticated and authorized to access resources. It can represent a user, an application, or even another system. Principals are typically identified by unique identifiers, such as usernames, email addresses, or service account IDs. In Shield Principals are of following type:

    1. User: A person or service account who can be a Principal. It is identified by an Email ID.
    2. Group: Collection of Users.
    3. All Registered Users: Collection of users who have registered in Shield. Any user who registers in Shield becomes part of this Principal.

    Project​

    By which we can group Resources, of various different Resource Types, who have common environment.

    Redirect URI​

    The Redirect URI is registered with the OIDC provider and serves as a callback URL, indicating the location which the OIDC provider redirects an authorized user with an authorization code or an ID token after authentication is complete.

    Resource​

    Entity which needs authorization to be accessed. For example, a GCE instance is a resource over which we need permission such as edit & view.

    Resource Type​

    Classification that contains Resource instances. For example, GCE can be a resource type for GCE instances.

    RBAC​

    Role-based access control (or RBAC) is a methodology for restricting app resources to only authorized users. RBAC defines primitives such as roles, resources, users, and policies to configure access control within an app

    Role​

    A Role is a collection of permissions or privileges that can be assigned to principals. Permissions determine what actions are allowed on a resource. Whenver we attach a role, a principal is granted all the permissions that the role contains.

    SpiceDB​

    SpiceDB is a Zanzibar-inspired open source database system for managing security-critical application permissions.

    SSO​

    A Single Sign-On (SSO) mechanism allows users to authenticate once with the authorization server and then access multiple applications or services without needing to reauthenticate for each one. OIDC supports SSO by providing a standardized way to authenticate and share user identity across applications.

    Open DataOps Foundation © 2023
    - + \ No newline at end of file diff --git a/configurations/index.html b/configurations/index.html index 9097ea5eb..c3a26cbda 100644 --- a/configurations/index.html +++ b/configurations/index.html @@ -7,13 +7,13 @@ - +

    Configuration

    Shield binary contains both the CLI client and the server. Each has it's own configuration in order to run. Server configuration contains information such as database credentials, spicedb connection, proxy, log severity, etc. while CLI client configuration only has configuration about which server to connect.

    Server Setup​

    There are several approaches to setup Shield Server

    1. Using the CLI
    2. Using the Docker
    3. Using the Helm Chart

    General pre-requisites​

    • PostgreSQL (version 13 or above)
    • SpiceDB

    Using the CLI​

    Using config file​

    Create a config file with the following command

    $ shield server init

    Alternatively you can use --config flag to customize to config file location.You can also use environment variables to provide the server configuration.

    Setup up the Postgres database, and SpiceDB instance and provide the details as shown in the example below.

    If you're new to YAML and want to learn more, see Learn YAML in Y minutes.

    Following is a sample server configuration yaml:

    config.yaml
    config.yaml
    version: 1

    # logging configuration
    log:
      # debug, info, warning, error, fatal - default 'info'
      level: debug

    app:
      port: 8000
      grpc:
        port: 8001
      # full path prefixed with scheme where resources config yaml files are kept
      # e.g.:
      # local storage file "file:///tmp/resources_config"
      # GCS Bucket "gs://shield/resources_config"
      resources_config_path: file:///tmp/resources_config
      # disable_orgs_listing if set to true will disallow non-admin APIs to list all organizations
      disable_orgs_listing: false
      # disable_orgs_listing if set to true will disallow non-admin APIs to list all users
      disable_users_listing: false
      # cors_origin is origin value from where we want to allow cors
      cors_origin: http://localhost:3000
      # configuration to allow authentication in shield
      authentication:
        # to use shield as session store
        session:
          # both of them should be 32 chars long
          # hash helps identify if the value is tempered with
          hash_secret_key: "hash-secret-should-be-32-chars--"
          # block helps in encryption
          block_secret_key: "block-secret-should-be-32-chars-"
        # once authenticated, server responds with a jwt with user context
        # this jwt works as a bearer access token for all APIs
        token:
          # generate key file via "./shield server keygen"
          # if not specified, access tokens will be disabled
          # example: /opt/rsa
          rsa_path: ""
          # issuer claim to be added to the jwt
          iss: "http://localhost.shield"
          # validity of the token
          validity: "1h"
        mail_otp:
          subject: "Shield - Login Link"
          # body is a go template with `Otp` as a variable
          body: "Please copy/paste the OneTimePassword in login form.<h2>{{.Otp}}</h2>This code will expire in 10 minutes."
          validity: "1h"
      # platform level administration
      admin:
        # Email list of users which needs to be converted as superusers
        # if the user is already present in the system, it is promoted to su
        # if not, a new account is created with provided email id and promoted to su.
        # UUIDs/slugs of existing users can also be provided instead of email ids
        # but in that case a new user will not be created.
        users: []
      # smtp configuration for sending emails
      mailer:
        smtp_host: smtp.example.com
        smtp_port: 587
        smtp_username: "username"
        smtp_password: "password"
        smtp_insecure: true
        headers:
          from: "username@acme.org"
    db:
      driver: postgres
      url: postgres://shield:@localhost:5432/shield?sslmode=disable
      max_query_timeout: 500ms

    spicedb:
      host: spicedb.localhost
      pre_shared_key: randomkey
      port: 50051

    See configuration reference for more details.

    Using environment variables​

    All the server configurations can be passed as environment variables using underscore _ as the delimiter between nested keys.

    .env 
    LOG_LEVEL=debug
    APP_PORT=8000
    APP_GRPC_PORT=8001
    APP_IDENTITY_PROXY_HEADER=X-Shield-Email
    DB_DRIVER=postgres
    DB_URL=postgres://shield:@localhost:5432/shield?sslmode=disable
    DB_MAX_QUERY_TIMEOUT=500ms
    SPICEDB_HOST=spicedb.localhost
    SPICEDB_PRE_SHARED_KEY=randomkey
    SPICEDB_PORT=50051
    SPICEDB_FULLY_CONSISTENT=false
    PROXY_SERVICES_0_NAME=test
    PROXY_SERVICES_0_HOST=0.0.0.0
    PROXY_SERVICES_0_PORT=5556
    PROXY_SERVICES_0_RULESET=file:///tmp/rules
    PROXY_SERVICES_0_RULESET_SECRET=env://TEST_RULESET_SECRET

    Set the env variable using export

    $ export DB_PORT = 5432

    Starting the server​

    Database migration is required during the first server initialization. In addition, re-running the migration command might be needed in a new release to apply the new schema changes (if any). It's safer to always re-run the migration script before deploying/starting a new release.

    To initialize the database schema, Run Migrations with the following command:

    $ shield server migrate

    To run the Shield server use command:

    $ shield server start

    Using --config flag​

    $ shield server migrate --config=<path-to-file>
    $ shield server start --config=<path-to-file>

    Using the Docker​

    To run the Shield server using Docker, you need to have Docker installed on your system. You can find the installation instructions here.

    You can choose to set the configuration using environment variables or a config file. The environment variables will override the config file.

    If you use Docker to build shield, then configuring networking requires extra steps. Following is one of doing it by running postgres and spicedb inside with docker-compose first.

    Go to the root of this project and run docker-compose.

    $ docker-compose up

    Once postgres and spicedb has been ready, we can run Shield by passing in the config of postgres and elasticsearch defined in docker-compose.yaml file.

    Using config file​

    Alternatively you can use the shield.yaml config file defined above and run the following command.

    $ docker run -d \
        --restart=always \
        -p 7400:7400 \
        -v $(pwd)/shield.yaml:/shield.yaml \
        --name shield-server \
        raystack/shield:<version> \
        server start -c /config.yaml

    Using environment variables​

    All the configs can be passed as environment variables using underscore _ as the delimiter between nested keys. See the example as discussed above

    Run the following command to start the server

    $ docker run -d \
        --restart=always \
        -p 7400:7400 \
        --env-file .env \
        --name shield-server \
        raystack/shield:<version> \
        server start

    Using the Helm chart​

    Pre-requisites for Helm chart​

    Shield can be installed in Kubernetes using the Helm chart from https://github.com/raystack/charts.

    Ensure that the following requirements are met:

    • Kubernetes 1.14+
    • Helm version 3.x is installed

    Add Raystack Helm repository​

    Add Raystack chart repository to Helm:

    helm repo add raystack https://raystack.github.io/charts/

    You can update the chart repository by running:

    helm repo update

    Setup helm values​

    The following table lists the configurable parameters of the Shield chart and their default values.

    See full helm values guide here and values.yaml file

    Install it with the helm command line:

    helm install my-release -f values.yaml raystack/shield

    Client Initialisation​

    Add a client configurations file with the following command:

    shield config init

    Open the config file and edit the gRPC host for Shield CLI

    shield.yaml
    client:
      host: localhost:8081

    List the client configurations with the following command:

    shield config list

    Required Header/Metadata in API​

    In the current version, all HTTP & gRPC APIs in Shield requires an identity header/metadata in the request. The header key is configurable but the default name is X-Shield-Email.

    If everything goes well, you should see something like this:

    2023-05-17T00:02:54.324+0530    info    shield starting {"version": "v0.5.1"}
    2023-05-17T00:02:54.331+0530    debug   resource config cache refreshed {"resource_config_count": 0}
    2023-05-17T00:02:54.333+0530    info    Connected to spiceDB: localhost:50051
    2023-05-17T00:02:54.339+0530    info    metaschemas loaded      {"count": 4}
    Open DataOps Foundation © 2023
    - + \ No newline at end of file diff --git a/contribution/contribute/index.html b/contribution/contribute/index.html index bdb35a78f..2b80041b1 100644 --- a/contribution/contribute/index.html +++ b/contribution/contribute/index.html @@ -7,13 +7,13 @@ - +

    Contribution Process

    The following is a set of guidelines for contributing to Shield. These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request. Here are some important resources:

    • Concepts section will explain you about Shield architecture,
    • Our roadmap is the 10k foot view of where we're going, and
    • Github issues track the ongoing and reported issues.

    How can I contribute?​

    We use RFCS and GitHub issues to communicate ideas.

    • You can report a bug or suggest a feature enhancement or can just ask questions. Reach out on Github discussions for this purpose.
    • You are also welcome to improve error reporting and logging and improve code quality.
    • You can help with documenting new features or improve existing documentation.
    • You can also review and accept other contributions if you are a maintainer.

    Please submit a PR to the main branch of the Shield repository once you are ready to submit your contribution. Code submission to Shield (including submission from project maintainers) require review and approval from maintainers or code owners. PRs that are submitted need to pass the build. Once build is passed community members will help to review the pull request.

    Becoming a maintainer​

    We are always interested in adding new maintainers. What we look for is a series of contributions, good taste, and an ongoing interest in the project.

    • Maintainers will have write access to the Shield repository.
    • There is no strict protocol for becoming a maintainer. Candidates for new maintainers are typically people that are active contributors and community members.
    • Candidates for new maintainers can also be suggested by current maintainers.
    • If you would like to become a maintainer, you should start contributing to Shield in any of the ways mentioned. You might also want to talk to other maintainers and ask for their advice and guidance.

    Guidelines​

    Please follow these practices for you change to get merged fast and smoothly:

    • Contributions can only be accepted if they contain appropriate testing (Unit and Integration Tests).
    • If you are introducing a completely new feature or making any major changes in an existing one, we recommend to start with an RFC and get consensus on the basic design first.
    • Make sure your local build is running with all the tests and checkstyle passing.
    • If your change is related to user-facing protocols / configurations, you need to make the corresponding change in the documentation as well.
    • Docs live in the code repo under docs so that changes to that can be done in the same PR as changes to the code.
    Open DataOps Foundation © 2023
    - + \ No newline at end of file diff --git a/index.html b/index.html index 2c7559fb2..da6d705bc 100644 --- a/index.html +++ b/index.html @@ -7,13 +7,18 @@ - +
    -

    Introduction

    Welcome to the introductory guide to Shield! We cover what Shield is, what problems it can solve, how it works, and how you can get started using it. If you are familiar with the basics of Shield, the guides provides a more detailed reference of available features.

    What is Shield?​

    Shield by Raystack is a role-based cloud-native user management system and authorization server for your applications and API endpoints. It is API-driven and provides CLI, HTTP/GRPC APIs and an Admin Portal. Shield is designed to be easy to use Identity and Access Management tool which handles user authentication by providing a Single-Sign-On(SSO) with any provider which adheres to the OIDC Protocol. It checks the client's credentials and permissions against the defined access policies before allowing or denying access to the backend services.

    Shield flow diagram

    How does shield work?​

    Here are the steps to work with Shield.

    1. Configure policies: This step involves definition of resource types that will exist in the connected backend. User can also configure the roles and permissions that exist.

    2. Configure rules: This step involves defining the authorization(via authz middleware) and resource creation(via hook) for each path in the backend.

    3. Making Shield proxy request: User can now hit at the shield server followed by the url path.

    Key Features​

    • Single-Sign-On(SSO): Shield implements the OpenID Connect(OIDC) Protocol that extends the OAuth 2.0 framework to provide authentication and identity information, allowing users to authenticate once and access multiple applications seamlessly. It also enables applications to obtain user identity information for authorization purposes. A Single login and logout for all the underlying application and resources ensure a seamless user experience.

    • Multiple sources of user identities: Shield allows seamless integration with any identity provider that supports OIDC, enabling a wide range of options for user authentication. This flexibility empowers organizations to leverage their preferred identity providers, such as Google, Microsoft Azure AD, Github, LinkedIn or others, to authenticate and manage user identities within their organisation's ecosystem.

    • Role-Based-Access-Control(RBAC): Shield follows the RBAC model, which means you can assign roles to users, groups, or service accounts. This simplifies access management by providing predefined roles with specific permissions, reducing the need for manual permission assignments.

    • Resource Management: Shield provides API to create and manage organizations/projects. Admins can create projects and groups within organizations. In addition, group admins can manage groups, add-remove members to the groups, and assign roles to these principals. Using Shield, admins can define policies which bind roles to the underlying resources.

    Using Shield​

    You can manage organizations, projects, group, users and resources in any of the following ways:

    Shield Command Line Interface​

    You can use the Shield command line interface to issue commands and to perform the entire Shield features. Using the command line can be faster and more convenient than using API. For more information on using the Shield CLI, see the CLI Reference page.

    HTTPS API​

    You can manage relation creation, checking authorization on a resource and much more by using the Shield HTTPS API, which lets you issue HTTPS requests directly to the service. For more information, see the API Reference page.

    Admin Portal​

    Besides HTTP APIs and CLI tool, Shield provides an provides an out-of-the-box UI for admins to configure SSO for the clients and manage roles, users, groups and organisations in one place.

    Where to go from here​

    See the installation page to install the Shield CLI. Next, we recommend completing the guides. The tour provides an overview of most of the existing functionality of Shield and takes approximately 30 minutes to complete.

    After completing the tour, check out the remainder of the documentation in the reference and concepts sections for your specific areas of interest. We've aimed to provide as much documentation as we can for the various components of Shield to give you a full understanding of Shield's surface area.

    Finally, follow the project on GitHub, and contact us if you'd like to get involved.

    Open DataOps Foundation © 2023
    - +

    Introduction

    Welcome to the introductory guide to Shield! We cover what Shield is, what problems it can solve, how it works, and how you can get started using it. If you are familiar with the basics of Shield, the guides provides a more detailed reference of available features.

    What is Shield?​

    Shield by Raystack is a role-based cloud-native user management system and authorization server for your applications and API endpoints. It is API-driven and provides CLI, HTTP/GRPC APIs and an Admin Portal. Shield is designed to be easy to use Identity and Access Management tool which handles user authentication by providing a Single-Sign-On(SSO) with any provider which adheres to the OIDC Protocol. It checks the client's credentials and permissions against the defined access policies before allowing or denying access to the backend services.

    Shield flow diagram

    How does shield work?​

    Here are the steps to work with Shield.

    1. Configure shield: Shield has various tuning parameters that can be configured to suit the needs of the organization. +This includes the configuration of the database, OIDC provider, email provider, etc.
    2. Configure policies: This step involves definition of resource types that will exist in the connected backend. +A resource is a protected backend service for example an order management service or user picture library. User can +also configure the roles and permissions to be assigned to the users.
    3. Connecting frontend: Shield provides a set of APIs that can be used by the frontend to authenticate, authorize and +manage users. The frontend can be a web application, mobile application or any other application that can make HTTP +requests.

    Key Features​

    • Single-Sign-On(SSO): Shield implements the OpenID Connect(OIDC) Protocol that extends the OAuth 2.0 framework to provide authentication and identity information, allowing users to authenticate once and access multiple applications seamlessly. It also enables applications to obtain user identity information for authorization purposes. A Single login and logout for all the underlying application and resources ensure a seamless user experience.

    • Multiple sources of user identities: Shield allows seamless integration with any identity provider that supports OIDC, enabling a wide range of options for user authentication. This flexibility empowers organizations to leverage their preferred identity providers, such as Google, Microsoft Azure AD, Github, LinkedIn or others, to authenticate and manage user identities within their organisation's ecosystem.

    • Role-Based-Access-Control(RBAC): Shield follows the RBAC model, which means you can assign roles to users, groups, or service accounts. This simplifies access management by providing predefined roles with specific permissions, reducing the need for manual permission assignments.

    • Resource Management: Shield provides API to create and manage organizations/projects. Admins can create projects and groups within organizations. In addition, group admins can manage groups, add-remove members to the groups, and assign roles to these principals. Using Shield, admins can define policies which bind roles to the underlying resources.

    Using Shield​

    You can manage organizations, projects, group, users and resources in any of the following ways:

    Shield Command Line Interface​

    You can use the Shield command line interface to issue commands and to perform the entire Shield features. Using the command line can be faster and more convenient than using API. For more information on using the Shield CLI, see the CLI Reference page.

    HTTPS API​

    You can manage relation creation, checking authorization on a resource and much more by using the Shield HTTPS API, which lets you issue HTTPS requests directly to the service. For more information, see the API Reference page.

    Admin Portal​

    Besides HTTP APIs and CLI tool, Shield provides an out-of-the-box UI for admins to configure SSO for the clients and manage roles, users, groups and organisations in one place.

    Where to go from here​

    See the installation page to install the Shield CLI. Next, we recommend completing the guides. The tour provides an overview of most of the existing functionality of Shield and takes approximately 30 minutes to complete.

    After completing the tour, check out the remainder of the documentation in the reference and concepts sections for your specific areas of interest. We've aimed to provide as much documentation as we can for the various components of Shield to give you a full understanding of Shield's surface area.

    Finally, follow the project on GitHub, and contact us if you'd like to get involved.

    Open DataOps Foundation © 2023
    + \ No newline at end of file diff --git a/installation/index.html b/installation/index.html index beb9c0540..1640e3188 100644 --- a/installation/index.html +++ b/installation/index.html @@ -7,15 +7,15 @@ - +

    Installation

    There are several approaches to install Shield.

    1. Using a pre-compiled binary
    2. Using the Docker image
    3. Installing from source
    4. Helm Charts

    Binary (Cross-platform)​

    Download the appropriate version for your platform from releases page. Once downloaded, the binary can be run from anywhere. You don’t need to install it into a global location. This works well for shared hosts and other systems where you don’t have a privileged account. -Ideally, you should install it somewhere in your PATH for easy use. /usr/local/bin is the most probable location.

    macOS​

    Shield is available via a Homebrew Tap, and as downloadable binary from the releases page:

    $ brew install raystack/taps/shield

    To upgrade to the latest version:

    $ brew upgrade shield

    Linux​

    Shield is available as downloadable binaries from the releases page. Download the .deb or .rpm from the releases page and install with sudo dpkg -i and sudo rpm -i respectively.

    Windows​

    Shield is available via scoop, and as a downloadable binary from the releases page:

    scoop bucket add shield https://github.com/raystack/scoop-bucket.git

    To upgrade to the latest version:

    scoop update shield

    Docker​

    We provide ready to use Docker container images. To pull the latest image: Make sure you have Spicedb and postgres running on your local and run the following.

    $ docker pull raystack/shield

    To pull a specific version:

    $ docker pull raystack/shield:v0.5.1

    To run the docker image with minimum configurations:

    $ docker run -p 8080:8080 \
      -e SHIELD_DB_DRIVER=postgres \
      -e SHIELD_DB_URL=postgres://shield:@localhost:5432/shield?sslmode=disable \
      -e SHIELD_SPICEDB_HOST=spicedb.localhost:50051 \
      -e SHIELD_SPICEDB_PRE_SHARED_KEY=randomkey
      -v .config:.config
      raystack/shield server start

    Building from source​

    Begin by cloning this repository then you have two ways in which you can build Shield:

    • As a native executable
    • As a docker image

    Run either of the following commands to clone and compile Shield from source

    $ git clone git@github.com:raystack/shield.git                 # (Using SSH Protocol)
    $ git clone https://github.com/raystack/shield.git             # (Using HTTPS Protocol)

    As a native executable​

    To build shield as a native executable, run make inside the cloned repository.

    $ make

    This will create the shield binary in the root directory. Initialise server and client config file. Customise the config.yaml file with your local configurations.

    $ ./shield config init

    Run database migrations

    $ ./shield server migrate

    Start Shield server

    $ ./shield server start

    As a Docker image​

    Building Shield's Docker image is just a simple, just run docker build command and optionally name the image

    $ docker build . -t shield

    Verifying the installation​​

    To verify if Shield is properly installed, run shield --help on your system. You should see help output. If you are executing it from the command line, make sure it is on your PATH or you may get an error about Shield not being found.

    $ ./shield --help

    What's next​

    Open DataOps Foundation © 2023
    - +Ideally, you should install it somewhere in your PATH for easy use. /usr/local/bin is the most probable location.

    macOS​

    Shield is available via a Homebrew Tap, and as downloadable binary from the releases page:

    $ brew install raystack/taps/shield

    To upgrade to the latest version:

    $ brew upgrade shield

    Linux​

    Shield is available as downloadable binaries from the releases page. Download the .deb or .rpm from the releases page and install with sudo dpkg -i and sudo rpm -i respectively.

    Windows​

    Shield is available via scoop, and as a downloadable binary from the releases page:

    scoop bucket add shield https://github.com/raystack/scoop-bucket.git

    To upgrade to the latest version:

    scoop update shield

    Docker​

    We provide ready to use Docker container images. To pull the latest image: Make sure you have Spicedb and postgres running on your local and run the following.

    $ docker pull raystack/shield

    To pull a specific version:

    $ docker pull raystack/shield:v0.6.2-arm64

    To run the docker image with minimum configurations:

    $ docker run -p 8080:8080 \
      -e SHIELD_DB_DRIVER=postgres \
      -e SHIELD_DB_URL=postgres://shield:@localhost:5432/shield?sslmode=disable \
      -e SHIELD_SPICEDB_HOST=spicedb.localhost:50051 \
      -e SHIELD_SPICEDB_PRE_SHARED_KEY=randomkey
      -v .config:.config
      raystack/shield server start

    Building from source​

    Begin by cloning this repository then you have two ways in which you can build Shield:

    • As a native executable
    • As a docker image

    Run either of the following commands to clone and compile Shield from source

    $ git clone git@github.com:raystack/shield.git                 # (Using SSH Protocol)
    $ git clone https://github.com/raystack/shield.git             # (Using HTTPS Protocol)

    As a native executable​

    To build shield as a native executable, run make inside the cloned repository.

    $ make

    This will create the shield binary in the root directory. Initialise server and client config file. Customise the config.yaml file with your local configurations.

    $ ./shield config init

    Run database migrations

    $ ./shield server migrate

    Start Shield server

    $ ./shield server start

    As a Docker image​

    Building Shield's Docker image is just a simple, just run docker build command and optionally name the image

    $ docker build . -t shield

    Verifying the installation​​

    To verify if Shield is properly installed, run shield --help on your system. You should see help output. If you are executing it from the command line, make sure it is on your PATH or you may get an error about Shield not being found.

    $ ./shield --help

    What's next​

    Open DataOps Foundation © 2023
    + \ No newline at end of file diff --git a/reference/api-auth/index.html b/reference/api-auth/index.html index 41073bb74..cfafda396 100644 --- a/reference/api-auth/index.html +++ b/reference/api-auth/index.html @@ -7,13 +7,13 @@ - +

    Authorization for APIs

    Client ID and Secret or Access Tokens are used to authorize privileged actions one can take on Shield APIs. It ensures that the action being performed in a Shield instance is by a user is already authenticated for it's identity in Shield and these actions are executed only when the user holds valid permissions to do so.

    Client ID and Secret​

    When using client id and secret on token or introspection endpoints, provide an Authorization header with a Basic auth value in the following form:

    Authorization: "Basic " + base64( client_id + ":" + client_secret )

    Creating a client id and secret​

    1. Create a service account inside an organization using Create Service User API
    2. Create the secret using Create Service User Secret API
    caution

    The client secret you have created is never persisted in the database and will only be displayed once. If you happen to lose the secret, you will need to generate a new one. It is crucial to save the client secret before closing the response.

    JWT Token​

    Alternatively, a Bearer token can also be used to verify user's identity.

    Authorization: "Bearer " + <JWT Token>

    Getting the Access token issued by Shield after user login​

    Access token by default is returned as part of the response header "x-user-token" after successful login with either an Email OTP or Social login. This can be requested again by sending a request to the Shield server with the cookies containing session details on endpoint /v1beta1/users/self.

    One can use this token as the Bearer token in Authorization headers.

    Creating JWT token from Private Keys for a service user​

    1. Create a service account inside an organization using Create Service User API
    2. Create using Create Service User Keys API
    caution

    The private key you created never persists in Shield and is only returned once. If you lose the private key, you will have to generate a new one. Public keys for a service user can be retrieved using this API

    1. Refer shield-go to see a Golang implementation to get a JWT token from private key using various libraries. This JWT token can be used in headers for user verification.

    2. Alternatively, Shield also exposes a Create Access Token API from Client ID and Secret. Use the access token returned from the API response in the headers for authentication as discussed above.

    X-Shield-Email​

    Warning

    Currently Shield CLI and APIs also allow an identity header like X-Shield-Email which can be configured via the server configurations file. This will be deprecated in the upcoming versions and should not be used in deployment.

    Open DataOps Foundation © 2023
    - + \ No newline at end of file diff --git a/reference/api-definitions/index.html b/reference/api-definitions/index.html index 1333af297..6072b2479 100644 --- a/reference/api-definitions/index.html +++ b/reference/api-definitions/index.html @@ -7,13 +7,13 @@ - +

    Proto Definitions

    Raystack/Proton is an open-source project developed by Raystack (Open DataOps Foundation) that provides a unified way to define and manage APIs in a microservices architecture. It aims to simplify the development and deployment of APIs by abstracting away the underlying implementation details.

    In Raystack/Proton, the Protobuf (protocol buffers) definitions are used to describe the structure and behavior of APIs. Protobuf is a language-agnostic binary serialization format developed by Google. It allows you to define the data models and API endpoints using a simple and concise syntax.

    In the context of Shield, the protobuf definitions are used to define the API endpoints and associated access control policies. These definitions specify the request and response message structures, allowed methods, and any additional metadata required for authorization checks.

    By leveraging the protobuf definitions with Protobuf compilers like protoc and buf, Shield automatically generates code for validating and enforcing the defined policies. It integrates with various frameworks and libraries to seamlessly enforce access control rules, ensuring that only authorized requests are allowed to access protected APIs and resources.

    The current deployment uses the v1beta1 Shield API version.

    info

    While making any changes in Shield APIs, the makefile in Shield contains the Proton commit hash, which is utilized in Shield for generating protobuf files and documentation with make proto and make doc rules.

    The make proto command creates apidocs.swagger.yaml specification which can be used to create a Postman collection to test these APIs.

    Besides this, one can import these files it in the Swagger Editor to visualize the Shield API documentation using the Swagger OpenAPI specification format.

    Open DataOps Foundation © 2023
    - + \ No newline at end of file diff --git a/reference/cli/index.html b/reference/cli/index.html index 5f2466c6e..33f556e36 100644 --- a/reference/cli/index.html +++ b/reference/cli/index.html @@ -7,13 +7,13 @@ - +

    CLI

    shield auth​

    Auth configs that need to be used with shield

    shield completion [bash|zsh|fish|powershell]​

    Generate shell completion scripts

    shield config <command>​

    Manage client configurations

    shield config init​

    Initialize a new client configuration

    shield config list​

    List client configuration settings

    shield environment​

    List of supported environment variables

    shield group​

    Manage groups

    shield group create [flags]​

    Upsert a group

    -f, --file string     Path to the group body file
    -H, --header string   Header <key>:<value>

    shield group edit [flags]​

    Edit a group

    -f, --file string   Path to the group body file

    shield group list​

    List all groups

    shield group view [flags]​

    View a group

    -m, --metadata   Set this flag to see metadata

    shield namespace​

    Manage namespaces

    shield namespace list​

    List all namespaces

    shield namespace view​

    View a namespace

    shield organization​

    Manage organizations

    shield organization admlist​

    list admins of an organization

    shield organization create [flags]​

    Upsert an organization

    -f, --file string     Path to the organization body file
    -H, --header string   Header <key>:<value>

    shield organization edit [flags]​

    Edit an organization

    -f, --file string   Path to the organization body file

    shield organization list​

    List all organizations

    shield organization view [flags]​

    View an organization

    -m, --metadata   Set this flag to see metadata

    shield permission​

    Manage permissions

    shield permission create [flags]​

    Upsert a permission

    -f, --file string     Path to the permission body file
    -H, --header string   Header <key>:<value>

    shield permission edit [flags]​

    Edit a permission

    -f, --file string   Path to the permission body file

    shield permission list​

    List all permissions

    shield permission view​

    View a permission

    shield policy​

    Manage policies

    shield policy create [flags]​

    Upsert a policy

    -f, --file string     Path to the policy body file
    -H, --header string   Header <key>:<value>

    shield policy edit [flags]​

    Edit a policy

    -f, --file string   Path to the policy body file

    shield policy view​

    View a policy

    shield project​

    Manage projects

    shield project create [flags]​

    Upsert a project

    -f, --file string     Path to the project body file
    -H, --header string   Header <key>:<value>

    shield project edit [flags]​

    Edit a project

    -f, --file string   Path to the project body file

    shield project list​

    List all projects

    shield project view [flags]​

    View a project

    -m, --metadata   Set this flag to see metadata

    shield role​

    Manage roles

    shield role create [flags]​

    Upsert a role

    -f, --file string     Path to the role body file
    -H, --header string   Header <key>:<value>

    shield role edit [flags]​

    Edit a role

    -f, --file string   Path to the role body file

    shield role list​

    List all roles

    shield role view [flags]​

    View a role

    -m, --metadata   Set this flag to see metadata

    shield seed [flags]​

    Seed the database with initial data

    -H, --header string   Header <key>

    shield server​

    Server management

    shield server init [flags]​

    Initialize server

    -o, --output string      Output config file path (default "./config.yaml")
    -r, --resources string   URL path of resources. Full path prefixed with scheme where resources config yaml files are kept
                             e.g.:
                             local storage file "file:///tmp/resources_config"
                             GCS Bucket "gs://shield-bucket-example"
                             (default: file://{pwd}/resources_config)
                             
    -u, --rule string        URL path of rules. Full path prefixed with scheme where ruleset yaml files are kept
                             e.g.:
                             local storage file "file:///tmp/rules"
                             GCS Bucket "gs://shield-bucket-example"
                             (default: file://{pwd}/rules)

    shield server keygen [flags]​

    Generate 2 rsa keys as jwks for auth token generation

    -k, --keys int   num of keys to generate (default 2)

    shield server migrate [flags]​

    Run DB Schema Migrations

    -c, --config string   config file path

    shield server migrate-rollback [flags]​

    Run DB Schema Migrations Rollback to last state

    -c, --config string   config file path

    shield server start [flags]​

    Start server and proxy default on port 8080

    -c, --config string   config file path

    shield user​

    Manage users

    shield user create [flags]​

    Upsert an user

    -f, --file string     Path to the user body file
    -H, --header string   Header <key>:<value>

    shield user edit [flags]​

    Edit an user

    -f, --file string   Path to the user body file

    shield user list​

    List all users

    shield user view [flags]​

    View an user

    -m, --metadata   Set this flag to see metadata

    shield version​

    Print version information

    Open DataOps Foundation © 2023
    - + \ No newline at end of file diff --git a/reference/configurations/index.html b/reference/configurations/index.html index d8ed2a1ad..52afd9f06 100644 --- a/reference/configurations/index.html +++ b/reference/configurations/index.html @@ -7,13 +7,13 @@ - +

    Server Configurations

    Sample Config
    config.yaml
    version: 1

    # logging configuration
    log:
      # debug, info, warning, error, fatal - default 'info'
      level: debug

    app:
      port: 8000
      grpc:
        port: 8001
      metrics_port: 9000
      identity_proxy_header: X-Shield-Email
      # full path prefixed with scheme where resources config yaml files are kept
      # e.g.:
      # local storage file "file:///tmp/resources_config"
      # GCS Bucket "gs://shield/resources_config"
      resources_config_path: file:///tmp/resources_config\
      # secret required to access resources config
      # e.g.:
      # system environment variable "env://TEST_RULESET_SECRET"
      # local file "file:///opt/auth.json"
      # secret string "val://user:password"
      # optional
      resources_config_path_secret: env://TEST_RESOURCE_CONFIG_SECRET
      # disable_orgs_listing if set to true will disallow non-admin APIs to list all organizations
      disable_orgs_listing: false
      # disable_orgs_listing if set to true will disallow non-admin APIs to list all users
      disable_users_listing: false
      # cors_origin is origin value from where we want to allow cors
      cors_origin: http://localhost:3000
      # configuration to allow authentication in shield
      authentication:
        # to use shield as session store
        session:
          # both of them should be 32 chars long
          # hash helps identify if the value is tempered with
          hash_secret_key: "hash-secret-should-be-32-chars--"
          # block helps in encryption
          block_secret_key: "block-secret-should-be-32-chars-"
        # once authenticated, server responds with a jwt with user context
        # this jwt works as a bearer access token for all APIs
        token:
          # generate key file via "./shield server keygen"
          # if not specified, access tokens will be disabled
          # example: /opt/rsa
          rsa_path: ""
          # issuer claim to be added to the jwt
          iss: "http://localhost.shield"
          # validity of the token
          validity: "1h"
        # external host used for oidc redirect uri, e.g. http://localhost:8000/v1beta1/auth/callback
        oidc_callback_host: http://localhost:8000/v1beta1/auth/callback
        # oidc auth server configs
        oidc_config:
          google:
            client_id: "xxxxx.apps.googleusercontent.com"
            client_secret: "xxxxx"
            issuer_url: "https://accounts.google.com"
            # validity of the verification duration
            validity: "10m"
        mail_otp:
          subject: "Shield - Login Link"
          # body is a go template with `Otp` as a variable
          body: "Please copy/paste the OneTimePassword in login form.<h2>{{.Otp}}</h2>This code will expire in 10 minutes."
          validity: "1h"
      # platform level administration
      admin:
        # Email list of users which needs to be converted as superusers
        # if the user is already present in the system, it is promoted to su
        # if not, a new account is created with provided email id and promoted to su.
        # UUIDs/slugs of existing users can also be provided instead of email ids
        # but in that case a new user will not be created.
        users: []
      # smtp configuration for sending emails
      mailer:
        smtp_host: smtp.example.com
        smtp_port: 587
        smtp_username: "username"
        smtp_password: "password"
        smtp_insecure: true
        headers:
          from: "username@acme.org"
    db:
      driver: postgres
      url: postgres://shield:@localhost:5432/shield?sslmode=disable
      max_query_timeout: 500ms

    spicedb:
      host: spicedb.localhost
      pre_shared_key: randomkey
      port: 50051
      # fully_consistent ensures APIs although slower than usual will result in responses always most consistent
      # suggested to keep it false for performance
      fully_consistent: false

    This page contains reference for all the application configurations for Shield.

    Version​

    FieldTypeDescriptionRequired
    versionintVersion number of the Shield configuration file.No

    Loggin Configuration​

    FieldTypeDescriptionRequired
    log.levelstringLogging level for Shield. Possible values debug, info, warning, error, fatalNo

    App Configuration​

    FieldDescriptionExampleRequired
    app.portPort number for HTTP communication.8000Yes
    app.grpc_portPort number for gRPC communication.8001Yes
    app.metrics_portPort number for metrics reporting.9000Yes
    app.hostHost address for the Shield application.127.0.0.1Yes
    app.identity_proxy_headerHeader key used for identity proxy.
    app.resources_config_pathFull path prefixed with the scheme where resources config YAML files are stored.
    Either new resources can be added dynamically via the apis, or can be passed in this YAML file    		No
    app.resources_config_path_secretSecret required to access resources config.No
    app.disable_orgs_listingIf set to true, disallows non-admin APIs to list all organizations.No
    app.disable_users_listingIf set to true, disallows non-admin APIs to list all users.No
    app.cors_originOrigin value from where CORS is allowed.Yes(for Admin UI)

    Authentication Configurations​

    Configuration to allow authentication in Shield.

    FieldDescriptionRequiredExample
    app.authentication.session.hash_secret_keySecret key for session hashing.Yes"hash-secret-should-be-32-chars--"
    app.authentication.session.block_secret_keySecret key for session encryption.Yes"block-secret-should-be-32-chars-"
    app.authentication.token.rsa_pathPath to the RSA key file for token authentication.Yes"./temp/rsa"
    app.authentication.token.issIssuer URL for token authentication.Yes"http://localhost.shield"
    app.authentication.oidc_callback_hostExternal host used for OIDC redirect URI.Yes"http://localhost:8000/v1beta1/auth/callback"
    app.authentication.oidc_config.google.client_idGoogle client ID for OIDC authentication.No"xxxxx.apps.googleusercontent.com"
    app.authentication.oidc_config.google.client_secretGoogle client secret for OIDC authentication.No"xxxxx"
    app.authentication.oidc_config.google.issuer_urlGoogle issuer URL for OIDC authentication.No"https://accounts.google.com"

    Admin Configurations​

    FieldDescriptionExampleRequired
    app.admin.usersEmail list of users to be converted as superusers.
    If the user is already present, they will be promoted to superuser.    		Optional

    Database Configurations​

    FieldDescriptionExampleRequired
    db.driverDatabase driver. Currently supports postgres.postgresYes
    db.urlDatabase connection URL.postgres://username:password@localhost:5432/databaseName?sslmode=disableYes
    db.max_idle_connsMaximum number of idle database connections.10No
    db.max_open_connsMaximum number of open database connections.10No
    db.conn_max_life_timeMaximum connection lifetime.10msNo
    db.max_query_timeoutMaximum query execution timeout.500msNo

    SpiceDB Configurations​

    FieldTypeDescriptionExampleRequired
    spicedb.hoststringHostname or IP address of the SpiceDB servicelocalhostYes
    spicedb.pre_shared_keystringRandom key for authentication and secure communication with SpiceDBrandom_keyYes
    spicedb.portuintPort number on which the SpiceDB service is listening50051Yes
    spicedb.fully_consistentbooleanEnable consistent API responses (slower but most consistent)falseNo
    Open DataOps Foundation © 2023
    - + \ No newline at end of file diff --git a/reference/metaschemas/index.html b/reference/metaschemas/index.html index eca240af8..7e1e61b9c 100644 --- a/reference/metaschemas/index.html +++ b/reference/metaschemas/index.html @@ -7,13 +7,13 @@ - +

    MetaSchemas

    MetaSchemas in Shield are default JSON-schemas designed to validate metadata that is included in the body of a resource. These schemas provide a standard way of describing the expected structure and content of metadata, which can be used to ensure consistency and accuracy of metadata across different resources.

    Why MetaSchemas?​

    Metadata is an essential component of many resources, including user profiles, organization descriptions, group memberships, and project details in Shield. However, the structure and content of metadata can vary widely between different resources, making it challenging to validate and compare metadata across resources.

    Metaschemas address this challenge by providing a standardized way of describing the expected structure and content of metadata. With the help of this, Shield users can ensure that metadata is consistently structured and accurately represents the information it is intended to convey.

    How Metaschemas Work!!​

    Metaschemas are based on the JSON schema format, typically including properties that describe the expected structure and content of metadata, such as data types, formats, required fields, and allowed values. Additionally it include properties that provide context about the metadata, such as a description of the metadata, a version number, and authorship information.

    For the ease of users of Shield, we populate the Shield database with default MetaSchemas for Users, Group, Organisation and Roles in Shield during the database migrations.

    One can easily updated these Schemas using the Shield MetaSchema APIs.

    Example MetaSchema​

    A sample user MetaSchema is given below, and the second tab shows an example user metadata which is valid according to the given example schema.

    {
      "title": "user metadata",
      "description": "JSON-schema for validating user metadata",
      "type": "object",
      "properties": {
        "label": {
          "title": "Label",
          "description": "Additional context about the user",
          "type": "object",
          "properties": {
            "role": {
              "type": "string",
              "title": "Role",
              "description": "User's designation in the org"
            }
          }
        },
        "description": {
          "title": "Description",
          "description": "Some additional information for the user",
          "type": "string"
        }
      },
      "additionalProperties": false
    }

    Note: The default user, organization, group and project MetaSchemas are in this repository

    Disabling MetaSchemas​

    In a Shield instance if one wants to diable the MetaSchema validation in either of users, group, organization or roles metadata. It is recommended to updated the MetaSchema's additionalProperties field value to true. Shield provides APIs to manipulate these schemas at the endpoint /v1beta1/meta/schemas. See the API Reference for more details.

    Open DataOps Foundation © 2023
    - + \ No newline at end of file diff --git a/reference/overview/index.html b/reference/overview/index.html index d02552590..9aac09c41 100644 --- a/reference/overview/index.html +++ b/reference/overview/index.html @@ -7,13 +7,13 @@ - +

    Overview

    Open DataOps Foundation © 2023
    - + \ No newline at end of file diff --git a/reference/shell-autocomplete/index.html b/reference/shell-autocomplete/index.html index a3d812397..33fd7e03f 100644 --- a/reference/shell-autocomplete/index.html +++ b/reference/shell-autocomplete/index.html @@ -7,14 +7,14 @@ - +

    Shell Autocompletion

    Bash auto-completion​

    The Shield completion script for Bash can be generated with shield completion bash. Sourcing this script in your shell enables the Shield completion.

    However, the completion script depends on bash-completion, which means that you have to install this software first (you can test if you have bash-completion already installed by running type _init_completion).

    note

    There are two versions of bash-completion, v1 and v2. V1 is for Bash 3.2 (which is the default on macOS), and v2 is for Bash 4.1+. The Shield completion script doesn't work correctly with bash-completion v1 and Bash 3.2. It requires bash-completion v2 and Bash 4.1+. Thus, to be able to correctly use Shield completion on macOS, you have to install and use Bash 4.1+ (instructions). The following instructions assume that you use Bash 4.1+ (that is, any Bash version of 4.1 or newer).

    You now have to ensure that the Shield completion script gets sourced in all your shell sessions. There are multiple ways to achieve this:

    • Source the completion script in your ~/.bash_profile file:
    echo 'source <(./shield completion bash)' >> ~/.bash_profile
    • Add the completion script to the /usr/local/etc/bash_completion.d directory:
    # To load completions for each session, execute once:
    # Linux:
    $ ./shield completion bash > /etc/bash_completion.d/_shield

    # macOS:
    $ ./shield completion bash > /usr/local/etc/bash_completion.d/_shield
    • If you installed Shield with Homebrew (as explained in getting started), then the shield completion script should already be in /usr/local/etc/bash_completion.d/_shield. In that case, you don't need to do anything.

    Note: The Homebrew installation of bash-completion v2 sources all the files in the BASH_COMPLETION_COMPAT_DIR directory, that's why the latter two methods work.

    In any case, after reloading your shell, Shield completion should be working.

    Zsh Auto-completion​

    The Shield completion script for Zsh can be generated with the command shield completion zsh. Sourcing the completion script in your shell enables shield autocompletion.

    • If shell completion is not already enabled in your environment, you will need to enable it. You can execute the following once:

    If you get an error like complete:13: command not found: compdef, then add the following to the beginning of your ~/.zshrc file:

      $ echo "autoload -U compinit; compinit" >> ~/.zshrc
    • To load completions for each session, execute once:
      $ shield completion zsh > "${fpath[1]}/_shield"
    • Now start a new shell for this setup to take effect and execute the below command to do sourcing in all your shell session:
      $ source ~/.zshrc

    After setup is completed

     # Run the following command in shell (bash/zsh)
     $ shield [tab][tab]

    Output contains the list of all the core-commands which can be auto-completed now:

    A cloud native role-based authorization aware reverse-proxy service.

    Usage
      shield <command> <subcommand> [flags]

    Core commands
      group           Manage groups
      namespace       Manage namespaces
      organization    Manage organizations
      permission      Manage permissions
      policy          Manage policies
      project         Manage projects
      role            Manage roles
      user            Manage users

    Other commands
      completion      Generate shell completion scripts
      config          Manage client configurations
      help            Help about any command
      server          Server management
      version         Print version information

    Help topics
      auth            Auth configs that need to be used with shield
      environment     List of supported environment variables
      reference       Comprehensive reference of all commands

    Flags
      --help   Show help for command

    Learn more
      Use 'shield <command> <subcommand> --help' for info about a command.
      Read the manual at https://raystack.github.io/shield/

    Feedback
      Open an issue here https://github.com/raystack/shield/issues
    Open DataOps Foundation © 2023
    - + \ No newline at end of file diff --git a/reference/smtp/index.html b/reference/smtp/index.html index 5dd595a55..40fccafe8 100644 --- a/reference/smtp/index.html +++ b/reference/smtp/index.html @@ -7,13 +7,13 @@ - +

    SMTP Server Configurations

    Shield can be used to send invites to users to join an organization currently or send OTPs (One Time Password) for verification. For this it implements a mailer service which provides the functionality to send emails using the configured SMTP(Simple Mail Transfer Protocol) server. This involves establishing a connection with the SMTP server, authenticating with the provided credentials, and delivering the email to the specified recipients.

    This document provides instructions on how to configure the SMTP settings for sending emails using the mailer configuration in Shield.

    Prerequisites​

    • SMTP server credentials (username and password)
    • SMTP server hostname and port information
    • Sender's Email address for the "from" header

    Configuration​

    To configure the SMTP settings for sending emails, follow the steps below:

    1. Open the shield server configuration file. Locate the mailer section.
    2. Update the following parameters within the mailer section:
      • smtp_host: Set this value to the hostname of your SMTP server. For example: smtp.example.com
      • smtp_port: Set this value to the port number used by your SMTP server. Typically, this is 587 for secure connections or 25 for insecure connections.
      • smtp_username: Enter the username or email address associated with your SMTP server account.
      • smtp_password: Enter the password for your SMTP server account.
      • smtp_insecure: If your SMTP server does not use a secure connection, set this value to true. If a secure connection (TLS/SSL) is required, set it to false.
      • headers.from: Set this value to the email address you want to appear in the "from" header when sending emails. For example, username@acme.org.

    Save the configuration file with the updated SMTP settings. And restart the Shield server.

    SMTP Providers​

    • Google Workspace SMTP: to use Google Workspace SMTP for sending mails, read this guide
    • Amazon SES service: to use Amazon SES for sending mails, follow this guide
    • MailGun: to use Mailgun, follow this guide
    • PostMark: to use PostMark SMTP service for sending mails from Shield, read this guide
    Open DataOps Foundation © 2023
    - + \ No newline at end of file diff --git a/support/index.html b/support/index.html index 7b84027da..f12b59ba9 100644 --- a/support/index.html +++ b/support/index.html @@ -7,13 +7,13 @@ - +
    Open DataOps Foundation © 2023
    - + \ No newline at end of file diff --git a/tenants/managing-resource/index.html b/tenants/managing-resource/index.html index 891142b5b..69a554cd7 100644 --- a/tenants/managing-resource/index.html +++ b/tenants/managing-resource/index.html @@ -7,14 +7,14 @@ - +

    Manage Resources

    A resource in Shield looks like

    FieldTypeDescription

    API Interface​

    Create resources​

    There are two ways to create a resource in the shield,

    API Interface​

    $ curl --location --request POST 'http://localhost:8000/v1beta1/projects/1b89026b-6713-4327-9d7e-ed03345da288/resources'
    --header 'Content-Type: application/json'
    --header 'Accept: application/json'
    --header 'X-Shield-Email: admin@raystack.org'
    --data-raw '{
      "name": "test-resource-beta",
      "projectId": "1b89026b-6713-4327-9d7e-ed03345da288",
      "namespaceId": "entropy/firehose",
      "relations": [
        {
          "subject": "user:john.doe@raystack.org",
          "roleName": "owner"
        }
      ]
    }'

    Proxy Hook​

    Users can add hooks to rules set to create a resource. The hook will be called after the proxy request is completed. Hooks can read query, header, params, payload, and response to get the values for Resource.

    - name: test-res
      path: /test-res
      target: "http://127.0.0.1:3000/"
      methods: ["POST"]
      frontends:
        - name: create test-res
          path: "/test-res"
          method: "POST"
          hooks:
            - name: authz
              config:
                attributes:
                  project:
                    key: project
                    type: json_payload
                  organization:
                    key: organization
                    type: json_payload
                  team:
                    key: team
                    type: json_payload
                  resource:
                    key: urns.#.id
                    type: json_payload

    List all resources across projects​

    $ curl --location --request GET 'http://localhost:8000/v1beta1/admin/resources'
    --header 'Accept: application/json'

    Get resources​

    $ curl -curl --location --request GET 'http://localhost:8000/v1beta1/projects/1b89026b-6713-4327-9d7e-ed03345da288/resources/28105b9a-1717-47cf-a5d9-49249b6638df'
    --header 'Accept: application/json'

    Update resource​

    $ curl --location --request PUT 'http://localhost:8000/v1beta1/projects/1b89026b-6713-4327-9d7e-ed03345da288/resources/a9f784cf-0f29-486f-92d0-51300295f7e8'
    --header 'Content-Type: application/json'
    --header 'Accept: application/json'
    --data-raw '{
      "name": "test-resource-beta1",
      "projectId": "1b89026b-6713-4327-9d7e-ed03345da288",
      "namespaceId": "entropy/firehose"
    }'
    Open DataOps Foundation © 2023
    - + \ No newline at end of file diff --git a/tenants/org/index.html b/tenants/org/index.html index e458d7375..3ddee8a01 100644 --- a/tenants/org/index.html +++ b/tenants/org/index.html @@ -7,13 +7,13 @@ - +

    Organization

    Overview​

    An Organization in Shield is a top-level resource. Each Project, Group, User, and Audit logs (coming soon) belongs to an Organization. There can be multiple tenants in each Shield deployement and an Organization will usually represent one of your tenant.

    An Organization serves as a container for users, groups, projects and resources. Each organization can have its own set of admins and access control policies. Users from one organization are seperated from others.

    An Organization slug is must be unique in the entire Shield deployment. No two organization can have same the slug. Whenever a user creates an Organization, one is assigned the role of the Organization Admin by default.

    Users are shared between organizations: Any user may belong to multiple organizations and will be able to use the same identity to navigate between organizations.

    Permissions and Roles at Organization level​

    RolePermissionsDescription
    app_organization_ownerapp_organization_administerThe owner of an organization has full control over it. They can create, update, delete, and manage all aspects of the organization.
    app_organization_managerapp_organization_update
    app_organization_get    		A manager of an organization has the ability to update and manage the organization, but they cannot create or delete it.
    app_organization_viewerapp_organization_getA viewer of an organization can only view the organization's information. They cannot update or manage the organization in any way.

    Besides this an Organization Owner can add custom permissions and roles at the organization level.

    Deactivating an Organization​

    Disabling an organization suspends its access to IAM services and restricts its ability to perform IAM-related actions. This can be done for various reasons, such as temporary suspension of services, organizational restructuring, or security considerations.

    Enabling or disabling an organization helps administrators manage the access and privileges of the organization's members and controls their interaction with IAM services and resources.

    Deleting an Organization​

    danger

    Caution should be exercised when deleting an organization, as it cannot be undone. Deleting an Organization is fatal as it permanently removes the organization, including all associated groups and projects. While the user accounts themselves are not deleted, they will lose access to all the organization resources.

    Managing Organization​

    An Organization in Shield is a top-level resource. Each Project, Group, User, and Audit logs (coming soon) belongs to an Organization. There can be multiple tenants in each Shield deployement and an Organization will usually represent one of your tenant.

    FieldTypeDescription
    iduuidUnique Organization identifier
    namestringThe name of the organization. The name must be unique within the entire Shield instance. The name can contain only alphanumeric characters, dashes and underscores.
    Example:"shield-org1-acme"
    titlestringThe title can contain any UTF-8 character, used to provide a human-readable name for the organization. Can also be left empty.
    Example: "Acme Inc"
    metadataobjectMetadata object for organizations that can hold key value pairs defined in Organization Metaschema. The metadata object can be used to store arbitrary information about the organization such as labels, descriptions etc. The default Organization Metaschema contains labels and descripton fields. Update the Organization Metaschema to add more fields.
    Example:{"labels": {"key": "value"}, "description": "Organization description"}

    Note: Organization metadata values are validated using MetaSchemas in Shield Read More

    tip

    Some of these APIs require special privileges to access these endpoints and to authorize these requests, users may need a Client ID/Secret or an Access token to proceed. Read Authorization for APIs to learn more.

    Create an Organization​

    Any (human) user can create an Organization in Shield. The user must exist in Shield before procceding to create an Organization. This user will be assigned the role of Organization Admin once the action is completed successful and will contain all the necessary permissions to manage the org.

    Required Authorization: User request just needs to be authenticated and no particular roles/permission are required to proceed.

    You can create organizations using either the Admin Portal, Shield Command Line Interface or via the HTTP APIs.

    1. Using shield organization create CLI command
    2. Calling to POST /v1beta1/organizations API
    $ shield organization create --file=<path to the organization.json file>
    1. To create an organization via the Admin Portal:
      1. Navigate to Admin Portal > Organizations from the sidebar
      2. Select + New Organization from top right corner
      3. Enter basic information for your organization, and select Add Organization.

    Add Users to an Organization​

    Add users to an organization. A user must exists in Shield before adding it to an org. This request will fail if the user doesn't exists. This API accepts a list of comma seperated (human) user IDs to be added to the organization. In case a user is already a member of the organization, no action will be taken for that particular user.

    Required Authorization : A user/service account with the role Organization Admin or Organization Manager is authorized to take this action. Also any user being assigned with custom role with update permission at app/organization namespace can also perform this action.

    1. Using the POST /v1beta1/organizations/:id/users API
    $ curl -L -X POST 'http://127.0.0.1:7400/v1beta1/organizations/:id/users' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Basic dGVzdC1jbGllbnQtaWQ6dGVzdC1zZWNyZXQ=' \
    --data-raw '{
      "userIds": [
        "2e73f4a2-3763-4dc6-a00e-7a9aebeaa971"
      ]
    }'

    Invite user to an Organization​

    Invite user with email to an organization and optionally to the groups within that Org. A user must exists in Shield before sending the invitation otherwise the request will fail. Invitations expire in 7 days.

    Required Authorization : A user/service account with the role Organization Admin is authorized to take this action. Also any user being assigned with custom role with invitationcreate permission at app/organization namespace can also perform this action.

    1. Using POST /v1beta1/organizations/:orgId/invitations API
    $ curl -L -X POST 'http://127.0.0.1:7400/v1beta1/organizations/:orgId/invitations' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Basic dGVzdC1jbGllbnQtaWQ6dGVzdC1zZWNyZXQ=' \
    --data-raw '{
      "userId": "john.doe@raystack.org",
      "groupIds": [
        "4e76f4a2-3763-4dc6-b00e-7a9a5beaa923",
        "2e45f4a2-1539-4df6-a70e-7a9aebeaa952"
      ]
    }'

    List pending invitations​

    This API can be used to list all the pending invitations queued for an organization which the user haven't take any action on. Once the user accepts an invitation or rejects it, the invitation is deleted from the Shield database.

    Required Authorization : A user/service account with the role Organization Admin is authorized to take this action. Also any user being assigned with custom role with invitationlist or invitationcreate permission at the app/organization namespace can also perform this action.

    1. Using GET /v1beta1/organizations/:orgId/invitations API
    $ curl -L -X GET 'http://127.0.0.1:7400/v1beta1/organizations/:orgId/invitations' \
    -H 'Accept: application/json' \
    -H 'Authorization: Basic dGVzdC1jbGllbnQtaWQ6dGVzdC1zZWNyZXQ='

    Delete pending invitations​

    Delete a pending invitation queued for an organization.

    Required Authorization : Any user/service account with the role Organization Admin is authorized to take this action. Also the user for whom the invite was created can delete the invite. Any user being assigned with custom role with invitationcreate permission at the app/organization namespace for that particular organization can also perform this action.

    1. Using DELETE /v1beta1/organizations/:orgId/invitations/:id API
    $ curl -L -X DELETE 'http://127.0.0.1:7400/v1beta1/organizations/:orgId/invitations/:id' \
    -H 'Accept: application/json' \
    -H 'Authorization: Basic dGVzdC1jbGllbnQtaWQ6dGVzdC1zZWNyZXQ='

    View an organization users​

    This API only returns a list of human users in an Organization. For listing service users of the Org refer this API

    Required Authorization : Any user/service user with get permission at Organization level can perform this action. Meaning all the Organization users/service users with role Organization Admin , Organization Manager or an Organization Viewer can list the org users.

    1. Calling to GET /v1beta1/organizations/{id}/users API
    curl -L -X GET 'http://127.0.0.1:7400/v1beta1/organizations/:id/users' \
    -H 'Accept: application/json' \
    -H 'Authorization: Basic dGVzdC1jbGllbnQtaWQ6dGVzdC1zZWNyZXQ='

    Create custom role for an Organization​

    Required Authorization : Any user/service user with the role Organization Admin is authorized to take this action. Also any user being assigned a custom role with rolemanage permission at the app/organization namespace can also perform this action.

    1. Using the POST /v1beta1/permissions API.
      Note: Specify the namespace app/organization to create a org level custom permission
    $ curl -L -X POST 'http://127.0.0.1:7400/v1beta1/organizations/92f69c3a-334b-4f25-90b8-4d4f3be6b825/roles' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Basic dGVzdC1jbGllbnQtaWQ6dGVzdC1zZWNyZXQ=' \
    --data-raw '{
      "name": "app_organization_member",
      "permissions": [
        "app_organization_get",
        "app_organization_update",
        "app_organization_invitationcreate"
      ],
      "metadata": {"decription": "Custom Role with managing invitations permissions"},
      "title": "Organization Member"
    }'

    Enable or disable an Organization​

    Sets the state of the organization as disabled. The existing users in the org will not be able to access any organization resources when the org is disabled.

    Required Authorization : Any user/service account with the role Organization Admin is authorized to take this action. Also any user being assigned with custom role with delete permission at the app/organization namespace can also perform this action.

    1. Using POST /v1beta1/organizations/:id/disable API
    $ curl --location 'http://localhost:7400/v1beta1/organizations/adf997e8-59d1-4462-a4f2-ab02f60a86e7/disable' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --header 'Authorization: Basic dGVzdC1jbGllbnQtaWQ6dGVzdC1zZWNyZXQ=' \
    --data '{}'

    To Enable the Org again send the request on POST /v1beta1/organizations/:id/enable API in same way as described above

    Remove Organization User​

    Removes a user from the organization. The user will be removed from all the groups inside the Organization ans will lose all the access to underlying projects and resources, the user will not be deleted from the Shield instance.

    Required Authorization : A user/service account with the role Organization Admin or Organization Manager is authorized to take this action. Also any user being assigned with custom role with update permission at app/organization namespace can also perform this action.

    1. Calling to DELETE {HOST}/v1beta1/organizations/:id/users/:userId API
    $ curl -L -X DELETE 'http://127.0.0.1:7400/v1beta1/organizations/:id/users/:userId' \
    -H 'Accept: application/json' \
    -H 'Authorization: Basic dGVzdC1jbGllbnQtaWQ6dGVzdC1zZWNyZXQ='
    Open DataOps Foundation © 2023
    - + \ No newline at end of file diff --git a/tenants/project/index.html b/tenants/project/index.html index 6d3ce489c..e33665633 100644 --- a/tenants/project/index.html +++ b/tenants/project/index.html @@ -7,13 +7,13 @@ - +

    Project

    Projects in Shield are sub-resources within an organization. They allow for logical grouping of resources and users (including groups and service users). Each project can have its own set of permissions and access controls, enabling fine-grained control over resource allocation and user management.A single organization can contain multiple projects.

    Principals(user, groups, service users) can be assigned a pre-defined or a custom role at the project level if multiple resources in a project are to share the same role for a user. A Shield policy can be created for that Project namespace for enabling user to have same role for all the underlying resources. Say a user A has app_project_viewer role for both the applications say X and Y in a project.

    If fine-grained access is required, a Shield policy can be created to attach a principal to a particular resource along with the user role. This giving flexibility to manage user authorization to organization resources at minute levels. Using two different policies, the same user A can have app_project_viewer role for resource X and a app_project_manager role for application Y.

    Predefined Permissions and Roles at Project level​

    RolePermissionsDescription
    app_project_ownerapp_project_administerA project owner have permissions to manage and modify all aspects of the project, including configuration, settings, and access control. They can add or remove members, grant or revoke permissions, and perform all actions related to the project
    app_project_managerapp_project_update
    app_project_get
    app_organization_projectcreate
    app_organization_projectlist    		A project manager can update project information, create new projects within the organization, retrieve project details and list all projects under the organization.
    app_project_viewerapp_project_getA project viewer has read-only access to the application project. They can view project details, configurations, and information but cannot make any modifications or perform any actions that could alter the project's state.

    Besides this we can create custom permissions and roles at the project level.

    Deactivate and Reactivate a Project​

    Disabling an project suspends its access to granted principals and restricts its ability to perform IAM-related actions. This can be done for various reasons, such as temporary suspension of services for maintainence or updates, or security concerns.

    Enabling or disabling a project doesn't removes the policies or users associated with a project resources. However, the project resources wont't be avaliable for access by the users even though they might have relevant permissions to access them. Re-enabling the project restores the expected behaviours.

    Deleting a Project​

    danger

    Caution should be exercised when deleting a project, as it cannot be undone. Deleting a Project is fatal as it permanently removes the resources, including all associated users and policies.

    Managing Project

    • Create a project in an org
    • Create a project resource
    • View a project resources
    • Create a policy to attach user to a project with pre-defined roles
    • View a project users
    • List a project admins
    • Enable or disable a project

    A project in Shield looks like

    FieldTypeDescription
    iduuidUnique project identifier
    namestringThe name of the project. This name must be unique within the entire Shield instance. The name can contain only alphanumeric characters, dashes and underscores and must start with a letter.
    Example:"project-alpha"
    titlestringThe title can contain any UTF-8 character, used to provide a human-readable name for the project. Can also be left empty.
    Example:"Project Alpha"
    orgIduuidUnique Organization identifier to which the project belongs
    metadataobjectMetadata object for project that can hold key value pairs pre-defined in Project Metaschema. The metadata object can be used to store arbitrary information about the user such as label, description etc. By default the user metaschema contains labels and descriptions for the project. Update the same to add more fields to the user metadata object.
    Example:{"label": {"key1": "value1"}, "description": "Project Description"}

    API Interface​

    tip

    Some of these APIs require special privileges to access these endpoints and to authorize these requests, users may need a Client ID/Secret or an Access token to proceed. Read Authorization for APIs to learn more.

    Create projects​

    $ curl --location --request POST 'http://localhost:8000/v1beta1/projects'
    --header 'Content-Type: application/json'
    --header 'Accept: application/json'
    --data-raw '{
      "name": "Project Beta",
      "slug": "project-beta",
      "metadata": {
          "description": "Project Beta"
      },
      "orgId": "4eb3c3b4-962b-4b45-b55b-4c07d3810ca8"
    }

    List projects​

    $ curl --location --request GET 'http://localhost:8000/v1beta1/admin/projects'
    --header 'Accept: application/json'

    Get Projects​

    $ curl --location --request GET 'http://localhost:8000/v1beta1/projects/457944c2-2a4c-4e6f-b1f7-3e1e109fe94c'
    --header 'Accept: application/json'

    Update Projects​

    $ curl --location --request PUT 'http://localhost:8000/v1beta1/projects/457944c2-2a4c-4e6f-b1f7-3e1e109fe94c'
    --header 'Content-Type: application/json'
    --header 'Accept: application/json'
    --data-raw '{
      "name": "Project Beta",
      "slug": "project-beta",
      "metadata": {
          "description": "Project Beta by Raystack"
      },
      "orgId": "4eb3c3b4-962b-4b45-b55b-4c07d3810ca8"
    }'
    Open DataOps Foundation © 2023
    - + \ No newline at end of file diff --git a/tour/add-to-group/index.html b/tour/add-to-group/index.html index be0b758fa..45101e583 100644 --- a/tour/add-to-group/index.html +++ b/tour/add-to-group/index.html @@ -7,13 +7,13 @@ - +

    Adding to a group

    In this part we'll learn to add members and managers to a group. For this, we'll be using relations API. Also, we have added two new users to shield john.doe@raystack.org and doe.john@raystack.org.

    Add a Member to a Group​

    curl --location --request POST 'http://localhost:8000/v1beta1/relations'
    --header 'Content-Type: application/json'
    --data-raw '{
    "objectId": "86e2f95d-92c7-4c59-8fed-b7686cccbf4f",
      "objectNamespace": "group",
      "subject": "user:doe.john@raystack.org",
      "roleName": "member"
    }'
    {
      "relation": {
        "id": "7cd5d527-6304-4dc7-9e35-4b1a7d3988a0",
        "objectId": "86e2f95d-92c7-4c59-8fed-b7686cccbf4f",
        "objectNamespace": "group",
        "subject": "user:448d52d4-48cb-495e-8ec5-8afc55c624ca",
        "roleName": "group:member",
        "createdAt": null,
        "updatedAt": null
      }
    }

    Add a Manager to a Group​

    curl --location --request POST 'http://localhost:8000/v1beta1/relations'
    --header 'Content-Type: application/json'
    --data-raw '{
    "objectId": "86e2f95d-92c7-4c59-8fed-b7686cccbf4f",
      "objectNamespace": "group",
      "subject": "user:doe.john@raystack.org",
      "roleName": "manager"
    }'
    200
    {
        "relation": {
            "id": "d8c5d2ca-73db-4185-bed8-c802c212a287",
            "objectId": "86e2f95d-92c7-4c59-8fed-b7686cccbf4f",
            "objectNamespace": "group",
            "subject": "user:448d52d4-48cb-495e-8ec5-8afc55c624ca",
            "roleName": "group:manager",
            "createdAt": null,
            "updatedAt": null
        }
    }
    Open DataOps Foundation © 2023
    - + \ No newline at end of file diff --git a/tour/check-permissions/index.html b/tour/check-permissions/index.html index bdc05742a..9ab4b6b41 100644 --- a/tour/check-permissions/index.html +++ b/tour/check-permissions/index.html @@ -7,14 +7,14 @@ - +

    Checking permissions in SpiceDB

    In this part of the tour, we'll learn how can we use Shield's permission checking system. Through this we are going to verify all the relations we have created till now.

    We can either use the check API or zed tool. In this tour we will be using the zed tool.

    1 Check the owner of the organization​

    zed permission check organization:4eb3c3b4-962b-4b45-b55b-4c07d3810ca8 owner user:2fd7f306-61db-4198-9623-6f5f1809df11
    true

    2 Check the organization of the project​

    shield % zed permission check project:1b89026b-6713-4327-9d7e-ed03345da288 organization organization:4eb3c3b4-962b-4b45-b55b-4c07d3810ca8
    true

    3 Check the organization of the group​

    zed permission check group:86e2f95d-92c7-4c59-8fed-b7686cccbf4f organization organization:4eb3c3b4-962b-4b45-b55b-4c07d3810ca8
    true

    4 Check the owner group of the resource​

    zed permission check entropy/firehose:28105b9a-1717-47cf-a5d9-49249b6638df owner group:86e2f95d-92c7-4c59-8fed-b7686cccbf4f
    false

    Note, this returns a false, even though we created a relation, where this group was an owner of this resource. Let's revisit the authz schema for entropy/firehose where we have

    definition entropy/firehose {
        ...
        relation owner: user | group#membership
        ...
    }

    We gave the owner right not to the group, but the entities holding membership permisssion in the group schema, namely member + manager which are of type user.

    definition group {
        ...
        relation member: user
        relation manager: user
        permission membership = member + manager
        ...
    }

    So, all the members of the group have the permission on this resource, which we have validated below.

    zed permission check entropy/firehose:28105b9a-1717-47cf-a5d9-49249b6638df owner user:598688c6-8c6d-487f-b324-ef3f4af120bb
    true
    Open DataOps Foundation © 2023
    - + \ No newline at end of file diff --git a/tour/creating-group/index.html b/tour/creating-group/index.html index dfeaeafa5..66c7a119a 100644 --- a/tour/creating-group/index.html +++ b/tour/creating-group/index.html @@ -7,13 +7,13 @@ - +

    Creating a group in organization

    In this, we will be using the organization id of the organization we created. Groups in shield belong to one organization.

    curl --location --request POST 'http://localhost:8000/v1beta1/organizations/4eb3c3b4-962b-4b45-b55b-4c07d3810ca8/groups'
    --header 'Content-Type: application/json'
    --data-raw '{
        "name": "Data Streaming",
        "slug": "data-streaming",
        "metadata": {
            "description": "group for users in data streaming domain"
        },
        "orgId": "4eb3c3b4-962b-4b45-b55b-4c07d3810ca8"
    }'
    200
    {
        "group": {
            "id": "86e2f95d-92c7-4c59-8fed-b7686cccbf4f",
            "name": "Data Streaming",
            "slug": "data-streaming",
            "orgId": "4eb3c3b4-962b-4b45-b55b-4c07d3810ca8",
            "metadata": {
                "description": "group for users in data streaming domain"
            },
            "createdAt": "2022-12-07T17:03:59.456847Z",
            "updatedAt": "2022-12-07T17:03:59.456847Z"
        }
    }

    Relations Table​

    It got an entry for the role group:organization for the organization 4eb3c3b4-962b-4b45-b55b-4c07d3810ca8.

                      id                  | subject_namespace_id |              subject_id              | object_namespace_id |              object_id               |        role_id         |          created_at           |          updated_at           | deleted_at 
    --------------------------------------+----------------------+--------------------------------------+---------------------+--------------------------------------+------------------------+-------------------------------+-------------------------------+------------
     460c44a6-f074-4abe-8f8e-949e7a3f5ec2 | user                 | 2fd7f306-61db-4198-9623-6f5f1809df11 | organization        | 4eb3c3b4-962b-4b45-b55b-4c07d3810ca8 | organization:owner     | 2022-12-07 14:10:42.881572+00 | 2022-12-07 14:10:42.881572+00 | 
     10797ec9-6744-4064-8408-c0919e71fbca | organization         | 4eb3c3b4-962b-4b45-b55b-4c07d3810ca8 | project             | 1b89026b-6713-4327-9d7e-ed03345da288 | project:organization   | 2022-12-07 14:31:46.517828+00 | 2022-12-07 14:31:46.517828+00 | 
     29b82d6e-b6fd-4009-9727-1e619c802e23 | organization         | 4eb3c3b4-962b-4b45-b55b-4c07d3810ca8 | group               | 86e2f95d-92c7-4c59-8fed-b7686cccbf4f | group:organization     | 2022-12-07 17:03:59.537254+00 | 2022-12-07 17:03:59.537254+00 |
    (3 rows)
    Open DataOps Foundation © 2023
    - + \ No newline at end of file diff --git a/tour/creating-organization/index.html b/tour/creating-organization/index.html index 608ad389a..b0ed1882a 100644 --- a/tour/creating-organization/index.html +++ b/tour/creating-organization/index.html @@ -7,13 +7,13 @@ - +

    Creating an organization

    Before creating a new organization, let's create an organization admin user. Note, the metadata in the user body is validated using the default MetaSchemas defined in Shield. These metadata schema validations can always be changed or disabled. For more details read MetaSchema Guides.

    User creation in Shield​

    curl --location --request POST 'http://localhost:8000/v1beta1/users'
    --header 'Content-Type: application/json'
    --header 'X-Shield-Email: admin@raystack.org'
    --data-raw '{
        "name": "Shield Org Admin",
        "email": "admin@raystack.org",
        "metadata": {
            "label": {
                "foo":"bar"
            },
            "description":"some user details"
        }
    }'

    Expected response for the user created is of type.

    200
    {
        "user": {
            "id": "2fd7f306-61db-4198-9623-6f5f1809df11",
            "name": "Shield Org Admin",
            "slug": "admin_raystack_io",
            "email": "admin@raystack.org",
            "metadata": {
                "label": {
                    "key":"value"
                },
                "description":"some user details"
            },
            "createdAt": "2022-12-07T13:35:19.005545Z",
            "updatedAt": "2022-12-07T13:35:19.005545Z"
        }
    }

    From now onwards, we can use the above user to perform all the admin operations. Let's begin with organization creation.

    Organization creation in Shield​

    curl --location --request POST 'http://localhost:8000/v1beta1/organizations'
    --header 'Content-Type: application/json'
    --header 'X-Shield-Email: admin@raystack.org'
    --data-raw '{
        "name": "Raystack",
        "slug": "raystack",
        "metadata": {
            "description": "Open DataOps Foundation"
        }
    }'
    200
    {
        "organization": {
            "id": "4eb3c3b4-962b-4b45-b55b-4c07d3810ca8",
            "name": "Raystack",
            "slug": "raystack",
            "metadata": {
                "description": "Open DataOps Foundation"
            },
            "createdAt": "2022-12-07T14:10:42.755848Z",
            "updatedAt": "2022-12-07T14:10:42.755848Z"
        }
    }

    Now, let's have a look at relations table where an organization:owner relationship is created.

                      id                  | subject_namespace_id |              subject_id              | object_namespace_id |              object_id               |      role_id       |          created_at           |          updated_at           | deleted_at
    --------------------------------------+----------------------+--------------------------------------+---------------------+--------------------------------------+--------------------+-------------------------------+-------------------------------+------------
     460c44a6-f074-4abe-8f8e-949e7a3f5ec2 | user                 | 2fd7f306-61db-4198-9623-6f5f1809df11 | organization        | 4eb3c3b4-962b-4b45-b55b-4c07d3810ca8 | organization:owner | 2022-12-07 14:10:42.881572+00 | 2022-12-07 14:10:42.881572+00 |
    (1 row)
    Open DataOps Foundation © 2023
    - + \ No newline at end of file diff --git a/tour/creating-project/index.html b/tour/creating-project/index.html index 55fcfcdd5..706af7e0e 100644 --- a/tour/creating-project/index.html +++ b/tour/creating-project/index.html @@ -7,13 +7,13 @@ - +

    Creating a project in organization

    In this, we will be using the organization id of the organization we just created. Projects in shield belong to one organization.

    curl --location --request POST 'http://localhost:8000/v1beta1/projects'
    --header 'Content-Type: application/json'
    --data-raw '{
        "name": "Project Alpha",
        "slug": "project-alpha",
        "metadata": {
            "description": "Project Alpha"
        },
        "orgId": "4eb3c3b4-962b-4b45-b55b-4c07d3810ca8"
    }'
    200
    {
        "project": {
            "id": "1b89026b-6713-4327-9d7e-ed03345da288",
            "name": "Project Alpha",
            "slug": "project-alpha",
            "orgId": "",
            "metadata": {
                "description": "Project Alpha"
            },
            "createdAt": "2022-12-07T14:31:46.436081Z",
            "updatedAt": "2022-12-07T14:31:46.436081Z"
        }
    }

    Relations Table​

    It got an entry for the role project:organization for the organization 4eb3c3b4-962b-4b45-b55b-4c07d3810ca8.

                      id                  | subject_namespace_id |              subject_id              | object_namespace_id |              object_id               |        role_id         |          created_at           |          updated_at           | deleted_at 
    --------------------------------------+----------------------+--------------------------------------+---------------------+--------------------------------------+------------------------+-------------------------------+-------------------------------+------------
     460c44a6-f074-4abe-8f8e-949e7a3f5ec2 | user                 | 2fd7f306-61db-4198-9623-6f5f1809df11 | organization        | 4eb3c3b4-962b-4b45-b55b-4c07d3810ca8 | organization:owner     | 2022-12-07 14:10:42.881572+00 | 2022-12-07 14:10:42.881572+00 | 
     10797ec9-6744-4064-8408-c0919e71fbca | organization         | 4eb3c3b4-962b-4b45-b55b-4c07d3810ca8 | project             | 1b89026b-6713-4327-9d7e-ed03345da288 | project:organization   | 2022-12-07 14:31:46.517828+00 | 2022-12-07 14:31:46.517828+00 | 
    (2 rows)
    Open DataOps Foundation © 2023
    - + \ No newline at end of file diff --git a/tour/creating-user/index.html b/tour/creating-user/index.html index f03502c68..02a7658b2 100644 --- a/tour/creating-user/index.html +++ b/tour/creating-user/index.html @@ -7,14 +7,14 @@ - +

    Authenticating user via the external IDP

    Pre-requisites​

    When a user initiates the authentication process, Shield redirects them to the OIDC authorization endpoint provided by your external IDP (Google in this example).

    Upon successful verification, you will receive a JWT (JSON Web Token) from the IDP. This JWT can be used for subsequent authentication and authorization requests to your application's protected resources.

    Let's test how the entire flow for the end user look like using Shield. Make sure you have the Shield server up and running by now.

    From the current Shield directory which contains the example application, open the example/authn folder and run the main.go file.

    $ cd ./example/authn
    $ go run main.go
    1. Open your internet browser and navigate to http://localhost:8888 for the authentication demo.

    Authn-1 flow diagram

    1. Select the external identity provider from the list of supported providers.

    Authn-2 flow diagram

    1. Select an account to login with Google and proceed. If the user fills in valid credentials, the external IDP returns an authorization code to Shield.

    2. Upon receiving these authorization codes from external IDPs (Google here), Shield issues JSON Web Token that contains claims about the authenticated user. It typically includes information such as the user's unique identifier (sub), email address (email), name (name), profile picture URL (picture), and other user-related information. The ID token is digitally signed by the issuer(Shield), allowing the application to verify its authenticity.

      The access token can be used to make authorized API requests to services/application on behalf of the user, if needed. In this example demo, the frontend receives the JWT token from Shield server and will store it in the client session and pass the session id in cookies.

    Upon successful login, this demo app displays the payload of the JSON Web Token generated by Shield:

    Authn-3 flow diagram

    Let's break down the parts of this JWT token and see what it reveals about the user's identity to other services:

    ClaimDescriptionValue
    expExpiration TimeThis claim indicates the timestamp when the token will expire.
    In this case, the token is set to expire on June 17, 2023, at 16:22:15 UTC.
    iatIssued AtThis claim represents the timestamp when the token was issued. It specifies the exact moment the token was created.
    In this case, the token was issued on May 18, 2023, at 16:22:15 UTC.
    issIssuerThis claim identifies the issuer of the token. It specifies the URL of the entity that issued the token.
    In this case, the token was issued by "http://localhost.shield".
    jtiJWT IDThis claim provides a unique identifier for the JWT. It distinguishes the token from other tokens and can be useful for tracking and revoking tokens if necessary.
    The JWT ID of this token is "176c9c51-281e-440a-b70a-106efa3c80b2".
    nbfNot BeforeThis claim indicates the timestamp before which the token must not be accepted. It ensures that the token is not considered valid until a certain time has passed.
    In this case, the token is not valid before May 18, 2023, at 16:22:15 UTC.
    orgOrganizationThis claim indicates the organization to which the user belongs to. Since we haven't yet created an org, this field's value isn't provided in the JWT token
    subSubjectThis claim identifies the subject of the token, which typically refers to the user or entity the token represents (unique user uuid) which in this case "6829c011-4cc4-49d7-8756-14c811558d9c".

    The profile section verifies that the user is logged in and a user is created in Shield!!

    Authn-4 flow diagram

    Open DataOps Foundation © 2023
    - + \ No newline at end of file diff --git a/tour/intro/index.html b/tour/intro/index.html index fae56bfe0..14503e9fb 100644 --- a/tour/intro/index.html +++ b/tour/intro/index.html @@ -7,13 +7,13 @@ - +

    Introduction

    Welcome to this tour of Shield. In this tour, we will take you through setting up the Shield's server and configuring it to a backend service demonstrating Shield as a proxy.

    We are going to cover this tour in the following steps, and recommend you to do the same.

    • Server Setup and configuring a backend service
    • Registering an organization in Shield
    • Registering a project under that organization
    • Registering a group under this organization
    • Adding users to the group
    • Checking permissions using Zed tool
    • Making a call to the backend service via Shield(proxy)
    Open DataOps Foundation © 2023
    - + \ No newline at end of file diff --git a/tour/setup-idp-oidc/index.html b/tour/setup-idp-oidc/index.html index 81f72031d..e978c38dc 100644 --- a/tour/setup-idp-oidc/index.html +++ b/tour/setup-idp-oidc/index.html @@ -7,7 +7,7 @@ - + @@ -18,7 +18,7 @@ The private key is securely stored by the authorization server or identity provider (IDP) and is used to generate the digital signature on the tokens. The public key is made available to clients and relying parties to verify the authenticity and integrity of the tokens. In this configuration, the rsa_path parameter specifies the location of the RSA key files used for token generation.

    The issuer URL uniquely identifies the IDP or authorization server that issues the tokens.

    By configuring the RSA key path and issuer URL, Shield can generate tokens with appropriate signatures and metadata, allowing services/applications to securely verify and authenticate the tokens received from the Shield server after user authentication.

    Open DataOps Foundation © 2023
    - + \ No newline at end of file diff --git a/tour/shield-as-proxy/index.html b/tour/shield-as-proxy/index.html index 8d546c034..906aedbed 100644 --- a/tour/shield-as-proxy/index.html +++ b/tour/shield-as-proxy/index.html @@ -7,7 +7,7 @@ - + @@ -15,7 +15,7 @@

    Shield as a proxy

    Untill now, we were using Shield's admin APIs. Those were responsible for managing Shield's entities. Next, we are use Shield as a proxy.

    We had attached the backend service entropy to Shield earlier, and now we are going to create a firehose resource in it. Before, going ahead have a look at the configuration file below. Detailed explaining on this configuration file would be in resources/concepts.

    rules:
      - backends:
          - name: entropy
            target: "http://entropy.io"
            prefix: "/api"
            frontends:
              - name: list_firehoses
                path: "/api/firehoses"
                method: "GET"
              - name: list_firehoses
                path: "/api/firehoses/{firehose_id}"
                method: "GET"
              - name: create_firehose
                path: "/api/firehoses"
                method: "POST"
                hooks:
                  - name: authz
                    config:
                      action: authz_action
                      attributes:
                        resource:
                          key: firehose.name
                          type: json_payload
                        project:
                          key: X-Shield-Project
                          type: header
                          source: request
                        organization:
                          key: X-Shield-Org
                          type: header
                          source: request
                        resource_type:
                          value: "firehose"
                          type: constant
                        group_attribute:
                          key: X-Shield-Group
                          type: header
                          source: request
                      relations:
                        - role: owner
                          subject_principal: group
                          subject_id_attribute: group_attribute

    Let's make the following request.

    curl --location --request POST 'http://localhost:5556/api/firehoses'
    --header 'Content-Type: application/json'
    --header 'X-Shield-Email: admin@raystack.org'
    --header 'X-Shield-Org: 4eb3c3b4-962b-4b45-b55b-4c07d3810ca8'
    --header 'X-Shield-Project: 1b89026b-6713-4327-9d7e-ed03345da288'
    --header 'X-Shield-Group: 86e2f95d-92c7-4c59-8fed-b7686cccbf4f'
    --data-raw '{
        "created_by": "Shield Org Admin",
        "configuration": {
            "SOURCE_KAFKA_CONSUMER_CONFIG_AUTO_COMMIT_ENABLE": false,
            "SOURCE_KAFKA_CONSUMER_CONFIG_FETCH_MIN_BYTES": "1",
            "SOURCE_KAFKA_CONSUMER_CONFIG_MANUAL_COMMIT_MIN_INTERVAL_MS": "-1",
            "SOURCE_KAFKA_CONSUMER_CONFIG_AUTO_OFFSET_RESET": "latest",
            "SINK_TYPE": "log",
            "FILTER_ENGINE": "no_op",
            "RETRY_MAX_ATTEMPTS": "2147483647",
            "LOG_LEVEL": "INFO",
            "INPUT_SCHEMA_PROTO_CLASS": "xxxxx",
            "SOURCE_KAFKA_TOPIC": "delete-me-abcdef",
            "SCHEMA_REGISTRY_STENCIL_URLS": "xxxxx",
            "SOURCE_KAFKA_CONSUMER_CONFIG_MAX_POLL_RECORDS": "1000"
        },
        "replicas": 2,
        "title": "test-firehose-creation-xxxxx",
        "group_id": "5ea18244-8e7a-xxxx-xxxx-ddf4b3fe3698",
        "team": "data_engineering",
        "cluster": "g-xxxxx",
        "stream_name": "g-xxxxx",
        "description": "Creating this firehose for testing purpose.",
        "projectID": "g-xxxxx",
        "orgID": "26ab9a89-de8d-xxxx-xxxx-5ba3f84be7b2",
        "entity": "xxxxx"
    }'

    Now this request will produce a series of events.

    • It will hit Shield(proxy) at /api/firehoses path, since there are no middleware the request shall be forwarded to the backend. We expect that a resource will be created in entropy and we'll get a response.
    • Now, hooks will be engaged. We only have a single authz hook, which creates a resource inside Shield. It will use resource name, org, project and type from either of request, response or as a constant, to create a resource.
    • By deafult, no relation is created for this resource, but we can confire this. Here, we have configured to add the group with owner role.

    We'll get a firehose object sent by entropy as a response, though we don't have interest in that.

    201
    {
        "firehose": {
            "replicas": 2,
            "created_by": "Shield Org Admin",
            "title": "test-firehose-creation-xxxxx",
            "group_id": "5ea18244-8e7a-xxxx-xxxx-ddf4b3fe3698",
            "team": "data_engineering",
            "stream_name": "g-xxxxx",
            "description": "Creating this firehose for testing purpose.",
            "projectID": "g-xxxxx",
            "entity": "xxxxx",
            "environment": "integration",
            "name": "g-xxxxx-firehose-creation-xxxxx-firehose",
            "configuration": {
                "xxxxx": "xxxxx"
            },
            "state": "running",
            "stop_date": null,
            "status": {
                "xxxxx": "xxxxx"
            },
            "pods": ["xxxxx"]
        }
    }

    What we have interest in is going to the resource and relations tables and checking for the entries.

    Resource Table​

    It got an entry for the resource we just created.

                                           urn                                       |                             name                             |              project_id              |                org_id                |   namespace_id   |          created_at           |          updated_at           | deleted_at |               user_id                |                  id
    ---------------------------------------------------------------------------------+--------------------------------------------------------------+--------------------------------------+--------------------------------------+------------------+-------------------------------+-------------------------------+------------+--------------------------------------+--------------------------------------
     r/entropy/firehose/g-xxxxx-firehose-creation-xxxxx-firehose | g-xxxxx-firehose-creation-xxxxx-firehose | 1b89026b-6713-4327-9d7e-ed03345da288 | 4eb3c3b4-962b-4b45-b55b-4c07d3810ca8 | entropy/firehose | 2022-12-08 13:25:37.335962+00 | 2022-12-08 13:25:37.335962+00 |            | 2fd7f306-61db-4198-9623-6f5f1809df11 | 28105b9a-1717-47cf-a5d9-49249b6638df
    (1 row)

    Relations Table​

    It got an entry for the role entropy/firehose:owner for the group 86e2f95d-92c7-4c59-8fed-b7686cccbf4f.

                      id                  | subject_namespace_id |              subject_id              | object_namespace_id |              object_id               |        role_id         |          created_at           |          updated_at           | deleted_at
    --------------------------------------+----------------------+--------------------------------------+---------------------+--------------------------------------+------------------------+-------------------------------+-------------------------------+------------
     460c44a6-f074-4abe-8f8e-949e7a3f5ec2 | user                 | 2fd7f306-61db-4198-9623-6f5f1809df11 | organization        | 4eb3c3b4-962b-4b45-b55b-4c07d3810ca8 | organization:owner     | 2022-12-07 14:10:42.881572+00 | 2022-12-07 14:10:42.881572+00 |
     10797ec9-6744-4064-8408-c0919e71fbca | organization         | 4eb3c3b4-962b-4b45-b55b-4c07d3810ca8 | project             | 1b89026b-6713-4327-9d7e-ed03345da288 | project:organization   | 2022-12-07 14:31:46.517828+00 | 2022-12-07 14:31:46.517828+00 |
     29b82d6e-b6fd-4009-9727-1e619c802e23 | organization         | 4eb3c3b4-962b-4b45-b55b-4c07d3810ca8 | group               | 86e2f95d-92c7-4c59-8fed-b7686cccbf4f | group:organization     | 2022-12-07 17:03:59.537254+00 | 2022-12-07 17:03:59.537254+00 |
     0cec1f0a-68ef-4a70-aabd-f3dd1e0eacac | group                | 86e2f95d-92c7-4c59-8fed-b7686cccbf4f | entropy/firehose    | 28105b9a-1717-47cf-a5d9-49249b6638df | entropy/firehose:owner | 2022-12-08 13:25:37.550927+00 | 2022-12-08 13:25:37.550927+00 |
    (4 rows)
    Open DataOps Foundation © 2023
    - + \ No newline at end of file diff --git a/users/group/index.html b/users/group/index.html index 79b7fad5c..44464ccdf 100644 --- a/users/group/index.html +++ b/users/group/index.html @@ -7,13 +7,13 @@ - +

    Group

    • Create an org group
    • List an org groups
    • Add or invite users to a group
    • View a group members
    • Assign roles to group members
    • Remove a user from a group
    • Enable or disable a group

    A group in Shield looks like

    FieldTypeDescription
    iduuidUnique group identifier
    namestringThe name of the group. The name must be unique within the entire Shield instance. The name can contain only alphanumeric characters, dashes and underscores.
    titlestringThe title can contain any UTF-8 character, used to provide a human-readable name for the group. Can also be left empty.
    metadataobjectMetadata object for groups that can hold key value pairs defined in Group Metaschema. The metadata object can be used to store arbitrary information about the group such as labels, descriptions etc. The default Group Metaschema contains labels and descripton fields. Update the Group Metaschema to add more fields.
    Example:{"labels": {"key": "value"}, "description": "Group description"}
    orgIduuidThe organization ID to which the group belongs to.

    Note: group metadata values are validated using MetaSchemas in Shield Read More

    Create an organization group​

    1. Using shield group create CLI command
    2. Calling to POST /v1beta1/organizations/orgId/groups API
     $ curl --location --request POST 'http://localhost:8000/v1beta1/organizations/adf997e8-59d1-4462-a4f2-ab02f60a86e7/groups'
    --header 'Content-Type: application/json'
    --header 'Accept: application/json'
    --data-raw '{
      "name": "data-batching",
      "title": "Data Batching",
      "metadata": {
          "description": "group for users in data batching domain"
      }
    }'
    1. To create a group via the Admin Portal:

    i. Navigate to Admin Portal > Groups from the sidebar

    ii. Select + New Group from top right corner

    iii. Enter basic information for the group, and select Add Group

    List an organization groups​

    1. Using shield group list CLI command
    2. Calling to GET /v1beta1/organizations/orgId/groups API

    View an organization projects​

     curl --location 'http://localhost:8000/v1beta1/organizations/adf997e8-59d1-4462-a4f2-ab02f60a86e7/projects' 
    --header 'Accept: application/json'

    API Interface​

    Create groups​

    $ curl --location --request POST 'http://localhost:8000/v1beta1/groups'
    --header 'Content-Type: application/json'
    --header 'Accept: application/json'
    --data-raw '{
      "name": "Data Batching",
      "slug": "data-batching",
      "metadata": {
          "description": "group for users in data batching domain"
      },
      "orgId": "4eb3c3b4-962b-4b45-b55b-4c07d3810ca8"
    }'

    List groups​

    $ curl --location --request GET 'http://localhost:8000/v1beta1/organizations/4eb3c3b4-962b-4b45-b55b-4c07d3810ca8/groups'
    --header 'Accept: application/json'

    Get groups​

    $ curl --location --request GET 'http://localhost:8000/v1beta1/organizations/4eb3c3b4-962b-4b45-b55b-4c07d3810ca8/groups/2105beab-5d04-4fc5-b0ec-8d6f60b67ab2'
    --header 'Accept: application/json'

    Update group​

    $ curl --location --request PUT 'http://localhost:8000/v1beta1/organizations/4eb3c3b4-962b-4b45-b55b-4c07d3810ca8/groups/2105beab-5d04-4fc5-b0ec-8d6f60b67ab2'
    --header 'Content-Type: application/json'
    --header 'Accept: application/json'
    --data-raw '{
        "name": "Data Batching",
        "slug": "data-batching",
        "orgId": "4eb3c3b4-962b-4b45-b55b-4c07d3810ca8",
        "metadata": {
            "description": "group for users in data batching domain",
            "org-name": "raystack"
        }
    }'

    Get all users in a group​

    curl --location --request GET 'http://localhost:8000/v1beta1/organizations/4eb3c3b4-962b-4b45-b55b-4c07d3810ca8/groups/86e2f95d-92c7-4c59-8fed-b7686cccbf4f/relations?subjectType=user&role=manager'
    --header 'Accept: application/json'
    Open DataOps Foundation © 2023
    - + \ No newline at end of file diff --git a/users/principal/index.html b/users/principal/index.html index 64f4544cf..00425f2b3 100644 --- a/users/principal/index.html +++ b/users/principal/index.html @@ -7,13 +7,13 @@ - +

    Principal

    Principal in Shield are entities that can be authenticated and authorized to access resources and perform actions. A principal will be used in controlling access to resources, as they can be associated with policies in Shield that define what actions the principal can perform and which resources they can access.

    Types of Principals in Shield​

    • User: A User Principal in Shield refers to an individual user who is granted certain privileges and access rights within the system. This type of principal is associated with a specific user account and is used to authenticate and authorize actions performed by the user. User principals are commonly used to manage and control access to resources, enforce security policies, and track user activities within the Shield system.

    • Service User: A Service User Principal is a type of principal in Shield that represents a non-human entity, such as a software application or a service, that interacts with the system. This principal is specifically designed to authenticate and authorize actions performed by automated processes or scripts, allowing machines to securely access and manipulate resources within the Shield environment. Machine User Principals are commonly used in scenarios where programmatic access is required without human intervention.

    • Group: A Group in Shield refers to a logical grouping of users or machine users who share common access rights and permissions. This type of principal simplifies the management of access control by assigning privileges and permissions to a group instead of individual users. Group principals enable administrators to efficiently define and enforce security policies across multiple users or machine users, making it easier to grant or revoke access to resources based on membership in a particular group.

    • Super User: Superusers are platform level admins used to manage a Shield instance. A Shield Super User have the highest level of access and control, allowing them to perform administrative tasks, configure settings, and manage other organization accounts. A superuser email can be added in configurations yaml while setting up the Shield server.

    info

    Constraints: In Shield, a (human) user can belong to more than one organization, but a Group will belong to only one organization that created it.

    Authenticating Principals​

    Shield authenticates a principal using OIDC (OpenID Connect) and the Magic Link approach. OIDC is an authentication protocol that allows applications to verify the identity of users and obtain their basic profile information. The Magic Link approach combines the simplicity of email-based authentication with the security of OIDC to create a seamless and secure authentication experience.

    Currently, users authenticate with the help of an external IdP, which issues security tokens that are then exchanged with the system.

    Authorizing Principals​

    Once a Shield principal is authenticated, the next step is authorization. Policies are used to define the permissions and access levels for each principal. These policies are attached to principals (users, or groups) and determine what actions they can perform on which resources.

    Deactivate and Reactivate a User​

    Disabling a user suspends its access to organization resources and restricts its ability to perform IAM-related actions. This can be done for various reasons, such as employee termination, account compromise, temporary suspension of services, or security considerations. When a user account is diabled it cannot be used to login to Shield. The user account is not deleted, it will lose access to all the organization resources. The user account can be re-enabled at any time.

    Enabling or disabling a user helps administrators manage the access and privileges of the users and controls their interaction with IAM services and resources.

    Delete a User​

    Deleting a user account permanently removes the user from the organization, including all associated groups and projects.

    note

    There must always be a minimum of one Admin in an Organization, so if the user being deleted is the sole Organization Admin, then this action should be halted until another user is promoted to the role of the Organization Admin.

    danger

    Caution should be exercised when deleting a user, as it cannot be undone. If the user account with same credentials is created again, it's organization, group and project memberships will not be restored.

    Managing Users​

    A project in Shield looks like

    FieldTypeDescription
    iduuidUnique user identifier
    namestringThe name of the user. The name must be unique within the entire Shield instance. The name can contain only alphanumeric characters, dashes and underscores and must start with a letter. If not provided, Shield automatically generates a name from the user email.
    Example:"john_doe_raystack_io"
    emailstringThe email of the user. The email must be unique within the entire Shield instance.
    Example:"john.doe@raystack.org"
    metadataobjectMetadata object for users that can hold key value pairs pre-defined in User Metaschema. The metadata object can be used to store arbitrary information about the user such as label, description etc. By default the user metaschema contains labels and descriptions for the user. Update the same to add more fields to the user metadata object.
    Example:{"label": {"key1": "value1"}, "description": "User Description"}
    titlestringThe title can contain any UTF-8 character, used to provide a human-readable name for the user. Can also be left empty.
    Example:"John Doe"

    Note: The metadata values are validated while creating and updating User using MetaSchemas in Shield Read More

    tip

    Some of these APIs require special privileges to access these endpoints and to authorize these requests, users may need a Client ID/Secret or an Access token to proceed. Read Authorization for APIs to learn more.

    Create users​

    Create a user in Shield with the given details. A user is not attached to an organization or a group by default, and can be invited to the org/group. The name of the user must be unique within the entire Shield instance. If a user name is not provided, Shield automatically generates a name from the user email.

    1. Using POST /v1beta1/users API
    2. Using shield user create CLI command
    curl -L -X POST 'http://127.0.0.1:7400/v1beta1/users' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    --data-raw '{
      "name": "john_doe_raystack_org",
      "email": "john.doe@raystack.org",
      "metadata": {
        "description": "Some User Description"
      },
      "title": "John Doe"
    }'

    List all users​

    Lists all the users from all the organizations in a Shield instance. The results can be filtered by keyword, organization, group and state.

    1. Using GET /v1beta1/users API
    2. Using shield user list CLI command (will list all users, no flags for filtering currently)
    $ curl -L -X GET 'http://127.0.0.1:7400/v1beta1/admin/users?pageSize=10&pageNum=2&keyword=John&orgId=4d726cf5-52f6-46f1-9c87-1a79f29e3abf&groupId=c2d85306-96f4-4895-98b4-c3e5c2f3084d&state=enabled' \
    -H 'Accept: application/json'

    Get User​

    Query a user in Shield by its unique id. In Shield a user can belong to more than one organizations, and result will get us a user in the entire Shield instance and not specific to an organization. 

    curl -L -X GET 'http://127.0.0.1:7400/v1beta1/users/e9fba4af-ab23-4631-abba-597b1c8e6608%20' \
    -H 'Accept: application/json'

    List User Organizations​

    To get all the organizations a particular user belongs to utilize the GET /v1beta1/users/:id/organizations API

    $ curl -L -X GET 'http://127.0.0.1:7400/v1beta1/users/e9fba4af-ab23-4631-abba-597b1c8e6608/organizations' \
    -H 'Accept: application/json'

    Accept and Decline an Organization Invitation​

    In Shield a user can be invited to an Organization and it's underlying Groups. A User can Accept or Descline the invitation with the following APIs.

    To Accept the invitation use POST /v1beta1/organizations/:orgId/invitations/:id/accept API

    curl -L -X POST 'http://127.0.0.1:7400/v1beta1/organizations/4d726cf5-52f6-46f1-9c87-1a79f29e3abf/invitations/e9fba4af-ab23-4631-abba-597b1c8e6608/accept' \
    -H 'Accept: application/json'

    To Decline the invitation use DELETE /v1beta1/organizations/:orgId/invitations/:id API. Here id is the unique invitation identifier.

    curl -L -X DELETE 'http://127.0.0.1:7400/v1beta1/organizations/4d726cf5-52f6-46f1-9c87-1a79f29e3abf/invitations/8e73f4a2-3763-4dc6-a00e-7a9aebeaa971' \
    -H 'Accept: application/json'

    List User Invitations​

    Update User​

    To Update a user title, metadata, name use PUT /v1beta1/users/:id API.
    Note: it is not allowed to update a user email in Shield.

    Shield also provides shield user edit CLI command for this operation.

    curl -L -X PUT 'http://127.0.0.1:7400/v1beta1/users/e9fba4af-ab23-4631-abba-597b1c8e6608' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    --data-raw '{
      "name": "john_doe_raystack_org",
      "email": "john.doe@raystack.org",
      "metadata": {
        "description": "Update User Description"
      },
      "title": "Johnny Doe"
    }'

    Disable and Enable a User​

    This operation temporarily remove the user from being invited to Organizations(and Groups), also disabling it's access to the Organization resources. The user won't be authenticated in the first place viaShield. But its organization/group memberships, policies remain intact. Once the user is enabled again, all it's relations are restored back.

    To disable a user use POST /v1beta1/users/:id/disable API

    curl -L -X POST 'http://127.0.0.1:7400/v1beta1/users/e9fba4af-ab23-4631-abba-597b1c8e6608/disable' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    --data-raw '{}'

    To enable it back use POST /v1beta1/users/:id/enable API

    curl -L -X POST 'http://127.0.0.1:7400/v1beta1/users/e9fba4af-ab23-4631-abba-597b1c8e6608/enable' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    --data-raw '{}'

    Delete User​

    Deleting a Shield user deletes it from the Shield instance and all it's relations to an Organization or Group. All the policies created for that user for access control and invitations for that user too is deleted.

    Use DELETE /v1beta1/users/:id API for this operation.

    curl -L -X DELETE 'http://127.0.0.1:7400/v1beta1/users/e9fba4af-ab23-4631-abba-597b1c8e6608' \
    -H 'Accept: application/json'
    Open DataOps Foundation © 2023
    - + \ No newline at end of file