What Oleria discovers
Once connected, Oleria continuously discovers and maps the following from your GitBook organization:- Accounts - every organization member, with their name, email address, the date they joined, and when they were last seen. Members whose membership GitBook has disabled appear as disabled. Guests - members with no organization role, who see only content shared with them - are marked as external users.
- Account roles - each member’s organization role: Admin, Creator, Reviewer, Editor, Commenter, Reader, or Guest. Admins are marked as admins.
- Sign-in - whether each member can sign in with SAML single sign-on, and whether your organization requires it. GitBook has no two-factor authentication of its own, so members who sign in without SSO show multi-factor authentication as not required, and members who must sign in through your identity provider show it as unavailable, because the identity provider enforces it.
- User groups - every team, with its members. Team owners appear as the team’s owners.
- Resources - your organization, every collection, space and docs site, and which collection each space or sub-collection belongs to. Deleted spaces appear as deleted, with no access.
- Access - who can reach each collection, space and site, and with which role:
- Members and teams given a role directly on a collection, space or site. When a member is set to No access on content, Oleria leaves them out of that content’s default access.
- The access each organization role gives through the content’s default permissions. When content inherits its permissions, Oleria follows the chain up through parent collections to the organization, where each member gets their own organization role. When content sets a specific role for everyone, every member except admins and guests gets that role. When content allows no access, only admins and the members and teams added to it can reach it.
- Admins’ access to all content, shown through the Organization Admin role’s admin access to every collection, space and site.
- Anonymous read access to published public and unlisted sites and to public and unlisted spaces. When any content is open to the internet, Oleria adds an account named Anyone on the internet with read access to it.
- Non-human identities (NHIs) - three kinds:
- Integrations installed on your organization, such as Slack or GitHub Sync, with the spaces and sites each one can reach and the permissions (scopes) the integration requests. A paused or pending installation appears as disabled, with no access.
- Private share links of each site. An active link reaches its site while the site is published to share-link visitors. Each link also appears as a credential. Oleria never reads the link’s URL, which contains its secret, and identifies each link by a fingerprint instead of its ID, because the ID is the secret part of the URL.
- Organization invite links, with the role anyone who uses the link joins with. Each link also appears as a credential. When your organization turns invite links off, every invite link appears as disabled.
- Credentials - besides share links and invite links, the signing certificate of each SAML provider, with its expiry date, and the signing key of each site that admits visitors through your own authentication. Oleria never reads the signing key itself.
- Activity - your organization’s audit log: changes to members, roles, teams, permissions, content and settings, with who made them. The audit log requires the GitBook Enterprise plan. See Known limitations.
Prerequisites
- A GitBook organization. The audit log, SAML single sign-on and team owners need the Enterprise plan; everything else works on any plan with members.
- A GitBook user with the Admin role in that organization, to own the personal access token. GitBook shows invite links and the audit log only to admins, and only admins can make the changes the remediation actions make. Oleria acts with this user’s permissions and refuses a token whose user isn’t an admin.
- Admin access to the Oleria workspace.
Create a GitBook personal access token
GitBook’s API authenticates with personal access tokens. A token has the same access as the user who creates it, and no scopes or expiry date.1
Sign in as the organization admin
Sign in to app.gitbook.com as the admin who will own the token.
2
Open developer settings
Open your account settings, then select Developer settings.
3
Create the token
Create a new token. Give it a name (for example,
Oleria), then copy the token.GitBook shows the token value only once, when you create it. Copy it now and store it securely.
4
Find your organization ID (optional)
Open your organization in GitBook and copy the ID from the URL: it’s the part after
/o/ in app.gitbook.com/o/<organization ID>/. You can skip this if the token’s user is an admin of only one organization.The exact location of these settings can change over time. If the steps above don’t match what you see, refer to GitBook’s own documentation.
Connect GitBook to Oleria
1
Open the integration
Go to your Oleria workspace, select Integrations -> select GitBook.
2
Complete the connection form
Fill in the connection form:
3
Confirm the connection
Select Authenticate. Before it saves anything, Oleria checks that:
- GitBook accepts the token.
- The organization exists and the token’s user is a member of it. If you left Organization ID blank, Oleria connects the organization the token’s user administers, and asks for the ID if they administer none or several.
- The token’s user has the Admin role in the organization.
Verify the integration
Confirm the GitBook organization appears on the Connected tab of your Oleria Integrations page with a status of Healthy. After the first sync completes, check that members, teams, collections, spaces, sites, integrations and links appear in your Oleria workspace.When you edit the integration, leave API token blank to keep the stored token. A new token must belong to an admin of the same organization. If the token is revoked or its user loses the Admin role, syncs fail until you update the integration.
Remediation actions
Oleria can take these actions in GitBook. Each one runs with the permissions of the user who owns the token, who must be an organization Admin. Before it offers an action, Oleria checks that the token works and that its user is an admin.
Keep these limits in mind when you use these actions:
- No disable or enable. GitBook’s API can’t disable a member, so Delete user is the only way to remove a member’s access from Oleria, and it can’t be reverted.
- Revoke permission removes only a direct role. If the user reaches the content through a team or their organization role, there’s no direct role to remove, so the action makes no change and its result lists the remaining access. To remove that access, remove the user from the team or change their organization role.
- Revoke anonymous access works only on sites. GitBook’s API can’t change a space’s visibility, so the action fails for a space. If the site is unpublished, or admits only visitors your own authentication signs in, the action makes no change.
- Reverting may need a plan upgrade. If GitBook requires a plan upgrade before a site can be published again, reverting Revoke anonymous access fails and the site stays offline.
- Reverting doesn’t undo later changes. If someone changed the member’s role, team membership, the content role or the share link after the action ran, reverting leaves it as it is and says so.
- A lost reply doesn’t fail a change that was made. If GitBook makes a change but its reply is lost, Oleria reads the member, team, content, site or link again. If the change shows, the action succeeds.
- Oleria won’t change the token owner’s own access, because the integration would lose access to the organization. This covers adding them to or removing them from a team, removing them from the organization, removing their role, and changing their content roles.
- Disable NHI fails if the target is gone. If the share link, invite link or integration no longer exists, the action fails instead of reporting success.
- Pending invitations can’t be reverted. When GitBook doesn’t add an invited user right away, the invitation waits until they accept, and GitBook’s API can’t cancel it. Revoke it in GitBook instead.
- External means guests. Remove access for external accounts works only on guests, members with no organization role, and fails for other members. Team memberships are kept, and the result lists them. Revoke access to an externally shared asset leaves members’ roles as they are and keeps the site published; use Revoke anonymous access to take it offline.
- External actions undo themselves on failure. If GitBook refuses a change part way through, Oleria gives back the roles it already removed and reports the failure.
Known limitations
- Audit log requires Enterprise. GitBook offers its audit log only on the Enterprise plan. On other plans, Oleria collects no activity and the rest of the sync is unaffected. The audit log isn’t yet verified against a live Enterprise organization, so activity types may be refined once GitBook’s action names are confirmed.
- No two-factor or password data. GitBook accounts have no password and GitBook has no two-factor authentication of its own, so there’s no last-password-change date or two-factor status. Which sign-in method a member uses (email link, Google or GitHub) isn’t available either, except SAML single sign-on.
- Personal access tokens aren’t discovered. GitBook has no API that lists users’ personal access tokens, including the one this integration uses.
- Pending invitations aren’t shown. Users invited by email appear only after they accept.
- Site permissions don’t flow into spaces. In GitBook, a site’s permissions can override the defaults of the spaces it publishes. Oleria shows a site’s permissions on the site, and each space’s own permissions and defaults on the space.
- A direct role lower than the default shows both. In GitBook, a role given directly on content overrides the member’s default access there. If that direct role is lower than the default (for example, Reader on a space where their default would be Editor), Oleria shows both, so reviews see the higher one. A direct No access is honoured.
- SAML providers and team owners require Enterprise. On other plans, SAML certificates and team owners aren’t shown.
- No owners for content or integrations. GitBook doesn’t record who created a space, collection, site, integration installation or link.