How might we build an authorization framework that is
● Easy for outside developers to integrate with
● Easy for Veterans to control access to their data
● Easy for us to maintain over time
● Allows for flexibility as standards and technology change?
● Insulates API owners from the implementation details of end-
user authorization
Based on where we felt we could be most effective, we focused on
product-centered questions:
How could you make authorization the best experience possible
for end users? And how can you ensure that the apps using our
APIs do the same?
Problem statement
● Five user research interviews
○ API consumers
○ API providers
○ Public sector APIs
● Industry research for best practices
○ Public and private sector APIs
Very high number of conversations given the short time frame of
this project = excellent data set
Methodology
Best authorization practices
for end users
4
Provide multiple 2FA options
and explain when necessary
why these security features
are in place
Be intentional about when
you require 2FA/MFA
Make it obvious what data is
being shared when
authorizing third party
applications
Use plain language in
privacy policies and terms of
service
Call out important pieces in
a summary and add detail
below
Allow a user to easily see
who has access to their
information
Allow a user to easily revoke
a third party’s access to their
information
Allow a user to access all
their data associated with an
account
Authorization API best practices
11
● Use established and tested technical standards
● Provide high quality documentation, and put it in the API docs
instead of in a privacy policy at the bottom that no one reads
● Refine the approach over time
● Provide self service options as much as possible but be
prepared for white glove support, especially in the beginning
● Require and reinforce best security and privacy practices for
API consumers dealing with PII; apply the standards where
they’re needed
When building APIs with authorization...
Provide comprehensive
documentation about
authorization
“I think bad documentation would be documentation that
excludes steps….Bad documentation would be, I make
the first call, it gives me a peace to authentication, but
they don't list what I need to do next to get the next
piece of authentication...As long as all the steps are
there and defined and I know exactly what I need to call,
what information I need to pass, I think the
documentation is good.”
Protect end user privacy and
maintain high security
standards
“Each agency can request what attributes they want to
receive. But, if an agency wants to use SSN, but they
only have a LOA1, we won’t allow that. LOA3 attributes
are first name, last name, address, SSN, driver's license.
We maintain that information in our database
encrypted...If you request an account deletion, we won’t
do it right away, we send an email, wait 24 hr, etc, in the
instance it’s a malicious users.”
“We have a demo meeting with the customer, they walk
us through the application, and then we ask them
questions about privacy policy/terms of service, how
they handle security and data breaches. “
Reinforce best practices
amongst consumers
“So if an agency wants to integrate with us they need to
have best practices, good documentation, and plan with
us in advance, documenting questions people could be
asking.”
● Evaluate other APIs that share PII to develop processes to
manage compliance over time
● Design and test lightweight prototypes for users to grant,
revoke, or review permissions they’ve granted for their data
● Continue to perform user research with API consumers so we
can refine the tools we provide for integration
● Technical discovery to ensure our authorization framework
with future flexibility in mind
● Simplify and streamline API Playbook
Recommended next steps
General best practices
17
Provide self-service options
to developers as much as
possible
“They have since done a whole new
dashboard where you can kind of go in
and see what configurations you have
out there and you can actually add the
configurations yourself instead of
going through them. So that helped
out a lot.”
Use past experiences of end
user results to inform
decisions when implementing
with a new consumer
“I would say they were able to provide us
guidance based on previous projects. They had
just gone through [integration with] Global Entry
and working with them so they were able to tell
us, you know, kind of use that as a use case and
say, well, in that case we would advise because
of our experience, they're not to do this and
maybe try this other thing.”
Provide open lines of
communication about
releases to API customers
“If we had known a delete account feature was
coming up a relatively soon, you know, maybe a
couple months out, then we could have had a lot
of discussions on that and see what changes we
want to make on our side to meet that new
feature that being implemented…”
“I think because of that change [releasing a new
feature] we asked for more advanced notice of
what changes they're making because we were
sort of getting them like the morning of.”
Provide versioning of APIs.
Versioning standards allow for
easier integration and future
development
“..typically an API would follow a versioning best practice
where there would be a version endpoint that was stable
so that all the groups using that API could develop
against it and you know, sort of have their flexibility to do
what they needed to do. But then also giving the team
who's developing that API, the ability to develop the next
version independently of all of the groups using the API.”
Embed provider team
members if possible during
API integration
“They [login.gov team] did provide .. a designer to work
with who had worked for awhile on their interface. They
could answer questions about the design decisions they
made there, as well as help vet our designs for possible
problems. He was just a really great reference for my
team and myself… to bounce ideas off of and to ask
questions… He was a guest in our slack and vice
versa….So we were able to get fairly immediate
answers when we are in the design phase.”
Give consumers data on use
cases that help sell reluctant
state holders on the value of
integrating with your API
“We've mostly tried to answer from our perspective: this
is the benefits and this is what it's costing us today and
what have you. But they [login.gov team] actually did
help quite a bit with convincing folks this [integrating with
their API] is the right way to go.”