Communicate API key change to users

yaelberger-commits commented 8 months ago

Description

As a GCNotify API user, I need to know that I'm required to send my full API key for an authorization request to send a job and not just 36 characters, so that I can successfully send my messages using the API without failures and 403 errors.

When you generate the API key, it’s generated with the prefix-name-service ID-secret part of the key
Previously, we would only take the last 36 characters of the Key.
We changed the documentation back in Aug 2022, but we didn’t do a full comms for this
Name of the key is variable so length of the full key will change
We don’t keep the full name of their key, if they haven’t noted it in their code in full, they might no longer know what it is, in which case they need to generate a new key and record the full key in their code base for future API auth requests
The API key is needed for every job a client wants to send through Notify using the API

WHY are we building? We made a change to how we accept API keys in our system to enhance security, and it will have an impact on how our clients use the API so we need a communications strategy and content to let them know about the changes.

WHAT are we building? An email to users with API key permissions, some changes to the API documentation under "Get Started," and a new 403 error description

VALUE created by our solution Clients will know what new actions they need to take to use GCNotify without issues and we will see less frustration, fewer errors and fewer support tickets about this issue where a job failed because a client failed to send their full API key for the authorization request

Documentation and Artifacts

Jan. 31, 2024 Story Refinement notes

not sending messages API key auth incident report

Acceptance Criteria

Given a client is using the API to send notifications, when they send their API key, then they know they need to send the full key, and not a partial key. If they did not know ahead of time, then they will see a 403 error with a description that tells them they need to use their full key.

[x] We need to figure out a timeline
3 weeks, 1 week then enforce
[x] Use query to get all clients with API key permissions http://localhost:1338/queries/288-user-list-of-all-individuals-who-have-api-management-permission

remove duplicates (for users who control multiple services)

[x] Dev review of the content
[ ] Pr needs to be deployed and merged to prd: https://github.com/cds-snc/notification-api/pull/2099 [March 6]
[x] FR review and translations
[x] Ioana to give a thumbs up to the approach, timeline and risks

Security:

[x] If you previously only sent us 36 characters, you now need to send us the full key now
[x] Any jobs sent using a partial key will fail and user will see a new error message

UX:

[x] Get rid of the “New” on the guidance in the API documentation under Get Started because this isn’t new anymore
[x] Update documentation so the examples of API keys have the prefix
[x] Doesn’t need to be in the Terms of Use
[x] We need to close the gap between people who set up their integration with the API before August 2022
[ ] Could be added to New Features (We’ve enhanced our security!)
[x] Consider a banner in GCNotify Admin so the full team can be accountable for this change
[x] If you’re only passing 36 characters of your API key, you’re not sending the full key.
[x] If you’re not a dev, pass this onto your dev team
[ ]

Dev

[x] New error message will tell clients that their job failed to send because they didn’t pass the full API key (403 message) Same code, just new description
[x] Write new error message description (not bilingual) “You need to send your full API key.”
A11y
Bilingualism
Privacy considerations
Security controls in place
Measuring success and metrics

Screenshot 2024-01-31 at 10.14.56 AM.png

yaelberger-commits commented 8 months ago

Hey team! Please add your planning poker estimate with Zenhub @yaelberger-commits @amazingphilippe @jzbahrai @YedidaZalik

yaelberger-commits commented 8 months ago

related to #1440 and the PR to enforce this change

YedidaZalik commented 8 months ago

Initial draft content being reviewed by Jumana API key error message and email

amazingphilippe commented 8 months ago

Yael and Jumana assigned to review.

yaelberger-commits commented 8 months ago

@YedidaZalik I did my review, added comments and left suggestions

YedidaZalik commented 8 months ago

Implemented Yael's suggestions. Waiting on approval for comms strategy before translating.

yaelberger-commits commented 8 months ago

Ioana is reviewing the email draft and will provide any comments

YedidaZalik commented 8 months ago

Sent to Marie-Sophie for translation

YedidaZalik commented 7 months ago

Translation is back https://docs.google.com/document/d/1gxx_517-w80SHi-jYT5zRBGJ5IQ_pCU8BPBSz6Wv1s8/edit#heading=h.gjdgxs

Combined into one email: https://docs.google.com/document/d/16izFHadnXtzt5bDEbKY_-32VxwVUOp7MdFvMHvmx_8Q/edit

foudamo commented 7 months ago

@yaelberger-commits will create a template on GC Notify

yaelberger-commits commented 7 months ago

I've created the template in GC Notify 2024-02-14 Full API Key next we need a Dev to run the query to get a current CSV list of users with "Manage API key" permissions

YedidaZalik commented 7 months ago

@yaelberger-commits @whabanks the error message is no longer showing in the google doc but it is:

Enter your full API key

whabanks commented 7 months ago

New API Error messages was added in the PR that will force users to use the full API key.

yaelberger-commits commented 7 months ago

Need a quick update the API documentation and email to reflect the full format for keys: “ApiKey-V1 gcntfy-bess-sseo-web-tst-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx-yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy”

whabanks commented 7 months ago

Do we need to add another bullet point, similar to the prefix bullet point, to explain ApiKey-v1? It's an internal version identifier.

Edit: We could lump it in with the prefix?

your API key prefix is ApiKey-v1 gcntfy

yaelberger-commits commented 7 months ago

+1 to lumping together @whabanks

whabanks commented 7 months ago

To confirm the draft email changes + translations today.

yaelberger-commits commented 7 months ago

draft email and translations have been updated today. Draft is ready to send out again Feb. 28th

whabanks commented 7 months ago

Updated look:

amazingphilippe commented 7 months ago

Sending second email today as a reminder. Last one will be sent March 5th

Need a dev to generate a new CSV

yaelberger-commits commented 7 months ago

For final send, we should remove duplicates (for users who control multiple services)

yaelberger-commits commented 7 months ago

Final email will need to go out March 5th at 10am ET @jzbahrai with this template https://notification.canada.ca/services/d6aa2c68-a2d9-4437-ab19-3ae8eb202553/templates/bbbd44c3-88f9-4208-9c76-1ae8df743795 March 6th we can release the code to production

jzbahrai commented 7 months ago

To discuss based on this slack thread: https://gcdigital.slack.com/archives/CV38DBNVA/p1709669549939889 we need to decide whether we are going to fork their code/ enforce changes for jwt

jzbahrai commented 7 months ago

To discuss based on this slack thread: https://gcdigital.slack.com/archives/CV38DBNVA/p1709669549939889 we need to decide whether we are going to fork their code/ enforce changes for jwt

mtoutloff commented 6 months ago

Need to discuss with Core, will set up next week

mtoutloff commented 6 months ago

Meeting scheduled for today that we will postpone and carry on with meeting when Jumana is back

mtoutloff commented 6 months ago

Meeting on this tomorrrow

cds-snc / notification-planning