github.com/esnet/gdg@v0.6.1-0.20240412190737-6b6eba9c14d8/website/content/docs/tutorials/orgs_auth.md (about)

     1  ---
     2  title: "Organization and Authentication"
     3  weight: 3
     4  date: 2023-09-01T00:00:00
     5  ---
     6  
     7  ## Concepts
     8  
     9  At it's core an Organization in grafana is an entity that allows you (the user) to organize and structure entities to seperate access for both usability
    10  and security.  So a Connection under org1 would never be able to be configured to use a dashboard under Org2.
    11  
    12  
    13  Authentication with GDG and grafana can take a few different patterns.
    14  
    15  1. Grafana Admin  - this is your typical admin/admin default user that comes with most installs.  You have full access to do everything.
    16  2. Org Admin - this is a user that is an admin for one or multiple Orgs and can manage most entities under the given org but not high level entities.
    17  
    18  Each user can be authenticated with 'BasicAuth' or APIKeys/Service Tokens.
    19  
    20   - Basic Auth allows a user to change Orgs context if they have access to more than one.
    21   - Service Token/API Keys are bound to a given org, so if the user tries to change the Org, it won't work.  It grants access, viewer, editor, admin for a given Org.
    22  
    23  
    24  If you are working with multiple Orgs, you will have a much easier time if you use basic auth.  You can certainly simply rotate the tokens as you like though GDG is a bit
    25  better at dealing with basic auth and switching orgs accordingly.
    26  
    27  
    28  ## Organization Workflow
    29  
    30  ### List Orgs (Grafana Admin)
    31  
    32  will retrieve all the components from Grafana and save to local file system.
    33  
    34  
    35  
    36  ```sh
    37  gdg backup orgs list
    38  
    39  ┌────┬───────────┐
    40  │ ID │ ORG       │
    41  ├────┼───────────┤
    42  │  1 │ Main Org. │
    43  │  2 │ DumbDumb  │
    44  │  3 │ Moo       │
    45  └────┴───────────┘
    46  ```
    47  
    48  Let's take a look at our context
    49  
    50  ```yaml
    51  ---local:
    52  storage: ""
    53  enterprise_support: false
    54  url: http://localhost:3000
    55  token: "SomeTokenHere"
    56  user_name: admin
    57  password: admin
    58  organization_name: Main Org.
    59  watched:
    60      - General
    61      - Other
    62  connections:
    63      credential_rules:
    64          - rules:
    65              - field: name
    66                regex: .*
    67            auth:
    68              user: user
    69              password: password
    70  datasources: {}
    71  filter_override:
    72      ignore_dashboard_filters: false
    73  output_path: test/data
    74  ```
    75  
    76  The organization_name is set to `Main Org.` and is the default if unspecified.
    77  
    78  
    79  ### Inspect Current Auth Org
    80  
    81  Let's have a look at our Token.
    82  
    83  ```sh
    84  gdg  tools  org tokenOrg
    85  ```
    86  
    87  ```
    88  ┌────┬───────────┐
    89  │ ID │ NAME      │
    90  ├────┼───────────┤
    91  │  1 │ Main Org. │
    92  └────┴───────────┘
    93  ```
    94  
    95  
    96  
    97  This is an immutable value and may cause issues if we switch.  Depending on the call the behavior is to give token preference or basic auth.  So if the basic auth is succesfully namespace into a given org, the token will still point to the wrong one and cause issues.  IF you wish to use Tokens, then avoid using basic auth.
    98  
    99  
   100  We can also look at what our User Org is set to  using:
   101  
   102  ```sh
   103  gdg tools org userOrg
   104  ```
   105  
   106  
   107  ```
   108  ┌────┬───────────┐
   109  │ ID │ NAME      │
   110  ├────┼───────────┤
   111  │  1 │ Main Org. │
   112  └────┴───────────┘
   113  ```
   114  This value though IS changeable.
   115  
   116  
   117  
   118  ### List Dashboards
   119  Now that we take a look at the dashboards under Org 1.
   120  
   121  ```sh
   122  gdg b dash list
   123  INFO[0002] Listing dashboards for context: 'local'
   124  ┌─────┬──────────────────────────────┬──────────────────────────────┬─────────┬───────────┬──────────────┬────────────────────────────────────────────────────────────────┐
   125  │  ID │ TITLE                        │ SLUG                         │ FOLDER  │ UID       │ TAGS         │ URL                                                            │
   126  ├─────┼──────────────────────────────┼──────────────────────────────┼─────────┼───────────┼──────────────┼────────────────────────────────────────────────────────────────┤
   127  │ 166 │ Bandwidth Dashboard          │ bandwidth-dashboard          │ General │ 000000003 │ netsage      │ http://localhost:3000/d/000000003/bandwidth-dashboard          │
   128  │ 167 │ Bandwidth Patterns           │ bandwidth-patterns           │ General │ 000000004 │ netsage      │ http://localhost:3000/d/000000004/bandwidth-patterns           │
   129  │ 174 │ Dashboard Makeover Challenge │ dashboard-makeover-challenge │ Other   │ F3eInwQ7z │              │ http://localhost:3000/d/F3eInwQ7z/dashboard-makeover-challenge │
   130  │ 175 │ Flow Analysis                │ flow-analysis                │ Other   │ VuuXrnPWz │ flow,netsage │ http://localhost:3000/d/VuuXrnPWz/flow-analysis                │
   131  │ 176 │ Flow Data for Circuits       │ flow-data-for-circuits       │ Other   │ xk26IFhmk │ flow,netsage │ http://localhost:3000/d/xk26IFhmk/flow-data-for-circuits       │
   132  │ 177 │ Flow Data for Projects       │ flow-data-for-projects       │ Other   │ ie7TeomGz │              │ http://localhost:3000/d/ie7TeomGz/flow-data-for-projects       │
   133  │ 178 │ Flow Data per Country        │ flow-data-per-country        │ Other   │ fgrOzz_mk │ flow,netsage │ http://localhost:3000/d/fgrOzz_mk/flow-data-per-country        │
   134  │ 179 │ Flow Data per Organization   │ flow-data-per-organization   │ Other   │ QfzDJKhik │ flow,netsage │ http://localhost:3000/d/QfzDJKhik/flow-data-per-organization   │
   135  │ 180 │ Flow Information             │ flow-information             │ Other   │ nzuMyBcGk │              │ http://localhost:3000/d/nzuMyBcGk/flow-information             │
   136  │ 181 │ Flows by Science Discipline  │ flows-by-science-discipline  │ Other   │ WNn1qyaiz │ flow,netsage │ http://localhost:3000/d/WNn1qyaiz/flows-by-science-discipline  │
   137  │ 169 │ Individual Flows             │ individual-flows             │ General │ -l3_u8nWk │ netsage      │ http://localhost:3000/d/-l3_u8nWk/individual-flows             │
   138  │ 168 │ Individual Flows per Country │ individual-flows-per-country │ General │ 80IVUboZk │ netsage      │ http://localhost:3000/d/80IVUboZk/individual-flows-per-country │
   139  │ 170 │ Loss Patterns                │ loss-patterns                │ General │ 000000006 │ netsage      │ http://localhost:3000/d/000000006/loss-patterns                │
   140  │ 171 │ Other Flow Stats             │ other-flow-stats             │ General │ CJC1FFhmz │ flow,netsage │ http://localhost:3000/d/CJC1FFhmz/other-flow-stats             │
   141  │ 172 │ Science Discipline Patterns  │ science-discipline-patterns  │ General │ ufIS9W7Zk │ flow,netsage │ http://localhost:3000/d/ufIS9W7Zk/science-discipline-patterns  │
   142  │ 173 │ Top Talkers Over Time        │ top-talkers-over-time        │ General │ b35BWxAZz │              │ http://localhost:3000/d/b35BWxAZz/top-talkers-over-time        │
   143  └─────┴──────────────────────────────┴──────────────────────────────┴─────────┴───────────┴──────────────┴────────────────────────────────────────────────────────────────┘
   144  ```
   145  
   146  ### Switching Organizations
   147  
   148  
   149  Switching context to Org 2.
   150  
   151  ```sh
   152  gdg tools orgs set 2
   153  INFO[0000] Succesfully set Org ID for context: local
   154  ```
   155  
   156  Let's confirm that we trully changed contexts.
   157  
   158  ```sh
   159  gdg tools org userOrg
   160  ```
   161  
   162  
   163  ```
   164  ┌────┬───────────┐
   165  │ ID │ NAME      │
   166  ├────┼───────────┤
   167  │  2 │ DumbDumb  │
   168  └────┴───────────┘
   169  ```
   170  
   171  ### Listing Orgs Dashboards
   172  
   173  Listing dashboards under Org 2 will result in an empty set.
   174  
   175  ```sh
   176  gdg b dash list
   177  INFO[0000] Listing dashboards for context: 'local'
   178  INFO[0000] No dashboards found
   179  ```
   180  
   181  Let's switch back to org 1 and donwload our dashboards.
   182  
   183  ```sh
   184  gdg tools orgs set 1
   185  INFO[0000] Succesfully set Org ID for context: local
   186  ```
   187  
   188  
   189  ### Download Orgs Dashboards
   190  
   191  ```sh
   192  gdg backup dash download
   193  ```
   194  
   195  ```
   196  INFO[0000] Importing dashboards for context: 'local'
   197  ┌───────────┬──────────────────────────────────────────────────────────────────────┐
   198  │ TYPE      │ FILENAME                                                             │
   199  ├───────────┼──────────────────────────────────────────────────────────────────────┤
   200  │ dashboard │ test/data/org_1/dashboards/General/bandwidth-dashboard.json          │
   201  │ dashboard │ test/data/org_1/dashboards/General/bandwidth-patterns.json           │
   202  │ dashboard │ test/data/org_1/dashboards/Other/dashboard-makeover-challenge.json   │
   203  │ dashboard │ test/data/org_1/dashboards/Other/flow-analysis.json                  │
   204  │ dashboard │ test/data/org_1/dashboards/Other/flow-data-for-circuits.json         │
   205  │ dashboard │ test/data/org_1/dashboards/Other/flow-data-for-projects.json         │
   206  │ dashboard │ test/data/org_1/dashboards/Other/flow-data-per-country.json          │
   207  │ dashboard │ test/data/org_1/dashboards/Other/flow-data-per-organization.json     │
   208  │ dashboard │ test/data/org_1/dashboards/Other/flow-information.json               │
   209  │ dashboard │ test/data/org_1/dashboards/Other/flows-by-science-discipline.json    │
   210  │ dashboard │ test/data/org_1/dashboards/General/individual-flows.json             │
   211  │ dashboard │ test/data/org_1/dashboards/General/individual-flows-per-country.json │
   212  │ dashboard │ test/data/org_1/dashboards/General/loss-patterns.json                │
   213  │ dashboard │ test/data/org_1/dashboards/General/other-flow-stats.json             │
   214  │ dashboard │ test/data/org_1/dashboards/General/science-discipline-patterns.json  │
   215  │ dashboard │ test/data/org_1/dashboards/General/top-talkers-over-time.json        │
   216  └───────────┴──────────────────────────────────────────────────────────────────────┘
   217  ```
   218  
   219  Please note the path has org_1 in the path.  Starting with version 0.5 of GDG we always namespace the entities we back by the org they belong to.