add API keys

[grizz]

From discussion with @daydr3am3r at #42

Key will be a 256bit random number, encoded with base62

API keys on the org level for sure, possibly per user as well?

Each key should allow a description and granular (CRUD) permissions the same as users within the org

[netravnen]

This should be be revived. (Asking. Because I do not know the status of the work behind this ticket.)

Currently I (as an example) am unable to use the API auth mechanism. Because I use an email address as the username. Plus password contains many non-[A-Za-z0-9] characters.

[2019-04-15T17:32:02Z]
$ curl -X GET https://user@example.com:P@ssword@peeringdb.com/api/org/1
curl: (3) Illegal port number

[2019-04-15T17:32:50Z]
$ curl -X GET https://user%40example.com:P%40ssword@peeringdb.com/api/org/1
{"meta": {"error": "Invalid username/password."}}

[arnoldnipper]

@netravnen curl --user user@example.com:P@ssword -X GET https://peeringdb.com/api/org/1 does also not work?

[netravnen]

@arnoldnipper

Yep. Worked. :D

Hadn't tried that. Because I only used what was written in the documentation for reference. Haven't (ever) had the need for authenticated use of GET calls with curl before. So did not look to closely at the curl parametres available.

Thou I still prefer if API keys gets implemented down the road. Is not to comfortable with my username+password possibly getting stored in plain text format in log files on my servers from where I execute the authenticated commands against the PDB API.

[arnoldnipper]

Thou I still prefer if API keys gets implemented down the road. Is not to comfortable with my username+password possibly getting stored in plain text format in log files on my servers from where I execute the authenticated commands against the PDB API.

You may also put your credentials in ~/.netrc which should be 600 and then call curl with the -n flag, like e.g.

curl -snG https://peeringdb.com/api/poc

to get the points of contacts which is the only information where you need a user account if you read information.

And of course: still +1 for providing API keys

[grrrrreg]

Is the documentation also on github so one can submit a PR when wanting to update it? (this was my intention after reading the thread) thx - Greg

…

On Wed, Apr 17, 2019 at 4:06 PM Arnold Nipper ***@***.***> wrote: *Thou I still prefer if API keys gets implemented down the road. Is not to comfortable with my username+password possibly getting stored in plain text format in log files on my servers from where I execute the authenticated commands against the PDB API.* You may also put your credentials in ~/.netrc which should be 600 and then call curl with the -n flag, like e.g. curl -snG https://peeringdb.com/api/poc to get the points of contacts which is the only information where you need a user account if you read information. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#266 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAH74H36OTXKSHVL3SXFAZLPQ6UO7ANCNFSM4EKP3KRQ> .

-- - Greg Villain | PeeringDB Product Committee +1 415-470-0194 | @grrrrreg <https://twitter.com/grrrrreg>

[grizz]

@grrrrreg Yep, with PR instructions: https://github.com/peeringdb/docs

[grizz]

I'm all for reviving it, +1 from me. @peeringdb/pc votes?

[mcmanuss8]

+1 API keys would be good

[grizz]

@peeringdb/ac @koalafil This has support from 3 people, let's do it!

[grizz]

@peeringdb/pc This needs one more vote from my current count, and #267 requires it be done, could we get another +1?

[arnoldnipper]

+1

[grizz]

Summary

• Add API keys (384bit base64)

Keys should be allowed at the org level with the same permissions management as users have.
Keys should be allowed at the user level with the option of making them either read only or full user access.

Keys should be passed as an HTTP header.

A tab will be added at the org admin to manage org level ones and a section in the user profile for the user level ones.

[grizz]

@peeringdb/pc please comment on the summary and make sure you agree with that design.

[arnoldnipper]

+1

[shane-kerr]

+1

[ccaputo]

@peeringdb/pc please comment on the summary and make sure you agree with that design.

@grizz, am not on @peeringdb/pc but I think your design is good. @peeringdb/pc can this get the go-ahead to proceed?

[egfrank]

Hi all!

20c is currently finalizing this feature but has a follow-up question.

Some actions that can be done by organization api keys require a contact point, such as creating a network (rdap validation will require an email) or creating an exchange or facility (verification queue and resulting deskpro tickets require an email).

Therefore we see the need to tie a user to organization api keys. We propose one of the following:

• Specify a contact user per organization key
• Specify one contact user for the whole organization

Can you weigh in on which option is more suitable?

@peeringdb/ac @peeringdb/pc

[ccaputo]

@peeringdb/pc, @peeringdb/ac, and others: Any reason not to drop the concept of organization api keys altogether, and instead for accountability only have user api keys? We don't have per-organization logins. Why should we have per-organization api keys when per-user logins have worked up to now?

From the standpoint of tracking down abuse/excessive-use, having an organization api key would mean that all (admin) users of the org have to be reached out to, and then they would need dig to try to track down who is responsible. From my experiences last year, in orgs with hundreds or thousands of employees this may not be a simple process. Thus I think we need a really really good reason for going beyond our current model of accountability. Orgs can create a 'role' admin user with a specific email, rather than have api keys for the whole org.

[mcmanuss8]

I think the risk of tying it to the user is that if the user leaves the org, the org's automation and tooling suddenly break, which is bad.
At many orgs, the software/tooling/devops people are not frequent peeringdb users so they don't even really have an account. As someone who manages a team of such people, I would strongly prefer keys not tied to a human

If it helps, maybe an email address for the tooling/software group would be good to associate to the key. So either we:

1. Encourage orgs to setup role users for automation and not individuals and tie the keys to those role users.
2. Setup org level keys and ask for an email address for a group we can reach instead of just an individual to help address poor API behavior.

[ccaputo]

That sounds good. Ie., to get the org api key, you have to provide a verified (in the PeeringDB sense) email address associated with it. And then when admins/ops need to reach out to a contact for api use that needs followup, that email can be used. @mcmanuss8 and @egfrank would that work?

[arnoldnipper]

• Encourage orgs to setup role users for automation and not individuals and tie the keys to those role users.

+1

[egfrank]

Hello all! Thanks for the feedback.

It sounds like two proposals have been made here, and I want to re-state them to you to confirm that we're all on the same page.

1. Remove org keys altogether. If an organization would like to set-up an API key for the purposes of the whole organization, they would set up a "role user", i.e. a new account in PeeringDB named something like "API Key Holder". They can set User Permissions for this "role user", and then when they set-up a User API Key for the "role" account, the API key will inherit the same permissions.
   My understanding of who has signed off on this is: Chris proposed this, @mcmanuss8 cited this as (1) in his comment, and Arnold gave it a +1

2. Keep org keys as a concept. To get an org key, though, you have to provide a PeeringDB verified email address associated with it so that we have a contact point for how the org key is being used. (This email address will also be necessary because, for example, if an request using an API key creates a facility, we need an email address for the resulting deskpro tickets).
   My understanding of who has signed off on this is: @mcmanuss8 cited this as (2) in his comment

Does that match everyone's understanding of:

• what the two proposed options are?
• who has signed off on which option?

And, in proposal 1, does this match everyone's expectation of what a "role" user looks like? I think that phrase could mean different things so I want to make sure we're on the same page.

Also, on 20c's end, we have already made good progress towards proposal (1). Proposal (2) would likely require more time than (1) to implement as it requires adding the point of contact to org keys.

[mcmanuss8]

Good summary @egfrank and I agree we don't have a clear consensus on which of those 2 approaches people want. I'm ok with both of them, but I think 2 is a bit cleaner.

@peeringdb/pc please vote for either:

1. Remove org keys altogether. If an organization would like to set-up an API key for the purposes of the whole organization, they would set up a "role user", i.e. a new account in PeeringDB named something like "API Key Holder". They can set User Permissions for this "role user", and then when they set-up a User API Key for the "role" account, the API key will inherit the same permissions.

2. Keep org keys as a concept. To get an org key, though, you have to provide a PeeringDB verified email address associated with it so that we have a contact point for how the org key is being used. (This email address will also be necessary because, for example, if an request using an API key creates a facility, we need an email address for the resulting deskpro tickets).

[ccaputo]

I'm happy to trust the @peeringdb/pc's decision on this.

[ynbrthr]

Good summary @egfrank and I agree we don't have a clear consensus on which of those 2 approaches people want. I'm ok with both of them, but I think 2 is a bit cleaner.

@peeringdb/pc please vote for either:

1. Remove org keys altogether. If an organization would like to set-up an API key for the purposes of the whole organization, they would set up a "role user", i.e. a new account in PeeringDB named something like "API Key Holder". They can set User Permissions for this "role user", and then when they set-up a User API Key for the "role" account, the API key will inherit the same permissions.

1. Keep org keys as a concept. To get an org key, though, you have to provide a PeeringDB verified email address associated with it so that we have a contact point for how the org key is being used. (This email address will also be necessary because, for example, if an request using an API key creates a facility, we need an email address for the resulting deskpro tickets).

I would lean toward 1, no org keys. Having role accounts, including for that purpose, is fairly standard.
That said, i don't feel strongly about it either way.

[arnoldnipper]

I'm ok with both of them, but I think 2 is a bit cleaner.

I fail to see why proposal 2 is cleaner. Proposal 1 fits in what we have. I'm still for 1. Only.

[mcmanuss8]

I'm ok with both of them, but I think 2 is a bit cleaner.

I fail to see why proposal 2 is cleaner. Proposal 1 fits in what we have. I'm still for 1. Only.

My argument for 2:

a) Decoupling the API key from a user and tying it to the organization more clearly specifies the desired relationship. The key is tied to org, not a user within the org
b) There's 0 enforcement of a user being a group/role user in 1 that I see
c) Multiple (real) users could easily see the org's API key in-app instead of having to pass it around out of band
d) Setting up another user just to hold an API key is another username/password for the org to remember to forget

[arnoldnipper]

a) Decoupling the API key from a user and tying it to the organization more clearly specifies the desired relationship. The key is tied to org, not a user within the org

There is no difference between an API key bound to a role-account or to an org.

b) There's 0 enforcement of a user being a group/role user in 1 that I see

True. That's up to the org to mark them as such. A couple of organisations are already using role accounts for the API.

c) Multiple (real) users could easily see the org's API key in-app instead of having to pass it around out of band

As @ccaputo pointed out from a security pov it would be way better to only have personal API keys. Admin users can see the key.

d) Setting up another user just to hold an API key is another username/password for the org to remember to forget

Same holds for the org API key.

[grizz]

I totally agree with 2 for many reasons, the main one being applications using the keys are tied to organizations, not users. $ORG has an internal business critical application, $USER sets it up, $USER then leaves company, application no longer works.

Also, I would think the API keys would just use an org wide email, but doing an email per API would be more granular.

a) Decoupling the API key from a user and tying it to the organization more clearly specifies the desired relationship. The key is tied to org, not a user within the org

Yes -- user churn should not affect application auth.

b) There's 0 enforcement of a user being a group/role user in 1 that I see

Not sure about that, but we could present org API keys to the org the same way we present users.

c) Multiple (real) users could easily see the org's API key in-app instead of having to pass it around out of band

Yes

d) Setting up another user just to hold an API key is another username/password for the org to remember to forget

Yes, and setting up a user for each API key is tedious and unnecessarily difficult to maintain.

[arnoldnipper]

I totally agree with 2 for many reasons, the main one being applications using the keys are tied to organizations, not users. $ORG has an internal business critical application, $USER sets it up, $USER then leaves company, application no longer works.

Also, I would think the API keys would just use an org wide email, but doing an email per API would be more granular.

a) Decoupling the API key from a user and tying it to the organization more clearly specifies the desired relationship. The key is tied to org, not a user within the org

Yes -- user churn should not affect application auth.

Errr ... the role-account is not bound to a real user. so, how would user churn affect that?

b) There's 0 enforcement of a user being a group/role user in 1 that I see

Not sure about that, but we could present org API keys to the org the same way we present users.

c) Multiple (real) users could easily see the org's API key in-app instead of having to pass it around out of band

Yes

d) Setting up another user just to hold an API key is another username/password for the org to remember to forget

Yes, and setting up a user for each API key is tedious and unnecessarily difficult to maintain.

Why would we have to set up a user for each API key?

[mcmanuss8]

Errr ... the role-account is not bound to a real user. so, how would user churn affect that?

Only by convention though - without enforcement, this would almost certainly be bypassed a non-trivial amount of time.

Why would we have to set up a user for each API key?

Well #1 would allow it by letting any user have an API key, right?

[arnoldnipper]

Why would we have to set up a user for each API key?

Well #1 would allow it by letting any user have an API key, right?

Option # 2 would still allow for per-user keys. Right? And we would allow a user to have unlimited numbers of API key. Right? Hence, why would we have to set up a user for each API key?

[egfrank]

For clarity, I understood both scenarios 1 and 2 as allowing the use case of individual user API keys. So that a user, if they chose, could create API keys for their own account for whatever personal use.

[arnoldnipper]

For clarity, I understood both scenarios 1 and 2 as allowing the use case of individual user API keys. So that a user, if they chose, could create API keys for their own account for whatever personal use.

That is also my understanding. Option 1 or 2 only deals non-specific user API keys.

[mcmanuss8]

I was thinking we wouldn't offer them at all. Do we have users who aren't associated with orgs who need API keys?

[arnoldnipper]

I was thinking we wouldn't offer them at all. Do we have users who aren't associated with orgs who need API keys?

And I was thinking we would need organisational/role-account keys only because organisations don't want to bind automation work to personal accounts. And I would always prefer API keys over user/pw authentication.

[grizz]

I was thinking we wouldn't offer them at all. Do we have users who aren't associated with orgs who need API keys?

Yes.

I was thinking we wouldn't offer them at all. Do we have users who aren't associated with orgs who need API keys?

And I was thinking we would need organisational/role-account keys only because organisations don't want to bind automation work to personal accounts. And I would always prefer API keys over user/pw authentication.

Yes.

So org API keys only :)

[grizz]

So, going back to see what the decision is, I think we've all agreed, we need org keys (edit: in addition to personal keys).

They will need an email address associated with them for things like verification and tickets, so when an org API key is added, we merely need a single email address field on it.

@peeringdb/pc any dissent?

[arnoldnipper]

Summary

• API key on the org level
  • needs an email address associated with it
  • can be created by any Admin of the organisation
• API key on the user level
• Key will be a 256bit random number, encoded with base62
• Each key should allow a description and granular (CRUD) permissions the same as users within the org